データ マッピング

データマッピングは、取り込み中に、受信データをテーブル内の列にマップするために使用されます。

Kusto では、さまざまな種類のマッピング row-oriented (CSV、JSON、AVRO と W3CLOGFILE)、および column-oriented (PARQUET と ORC) がサポートされています。

マッピングリストの各要素は、次の3つのプロパティから構成されます。

プロパティ 説明
Column テーブル内のターゲット列名
Datatype Optionalマップされた列がまだテーブルに存在しない場合に作成するデータ型
Properties Optional次の各セクションで説明するように、各マッピングに固有のプロパティを含むプロパティバッグ。

すべてのマッピングは 事前に作成 でき、パラメーターを使用してインジェストコマンドから参照できます ingestionMappingReference

CSV マッピング

ソースファイルが CSV (または任意の区切り記号区切り形式) で、そのスキーマが現在のテーブルスキーマと一致しない場合、CSV マッピングはファイルスキーマからテーブルスキーマにマップされます。 テーブルが Azure データエクスプローラーに存在しない場合は、このマッピングに従って作成されます。 テーブルにマッピングの一部のフィールドがない場合は、それらが追加されます。

CSV マッピングは、CSV、TSV、PSV、SCSV、SOHsv のすべての区切り記号で区切られた形式で適用できます。

リスト内の各要素には、特定の列のマッピングが記述され、次のプロパティが含まれる場合があります。

プロパティ 説明
Ordinal CSV 内の列の順序番号。
ConstantValue OptionalCSV ファイル内の値ではなく、列に使用される定数値。

注意

OrdinalConstantValue は同時に指定できません。

CSV マッピングの例

[
  {"Column": "event_time", "Properties": {"Ordinal": "0"}},
  {"Column": "event_name", "Properties": {"Ordinal": "1"}},
  {"Column": "event_type", "Properties": {"Ordinal": "2"}},
  {"Column": "ingestion_time", "Properties": {"ConstValue": "2021-01-01T10:32:00"}}
]

注意

上記のマッピングを制御コマンドの一部として指定すると、 .ingest JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="csv", 
        ingestionMapping = 
        '['
            '{"Column": "column_a", "Properties": {"Ordinal": 0}},'
            '{"Column": "column_b", "Properties": {"Ordinal": 1}}'
        ']'
    )

注意

上記のマッピングが 事前に作成 されている場合、コントロールコマンドで参照でき .ingest ます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="csv", 
        ingestionMappingReference = "MappingName"
    )

JSON マッピング

ソースファイルが JSON 形式の場合は、ファイルの内容がテーブルにマップされます。 マップされているすべての列に有効なデータ型が指定されていない限り、テーブルはデータベースに存在している必要があります。 存在しないすべての列にデータ型が指定されていない限り、JSON マッピングでマップされている列は、テーブル内に存在する必要があります。

リスト内の各要素には、特定の列のマッピングが記述され、次のプロパティが含まれる場合があります。

プロパティ 説明
Path 値が次で始まる場合 $ : json ドキュメント内の列のコンテンツになるフィールドへの json パス (ドキュメント全体がであることを示す json パス $ )。 値が次の値で始まらない場合 $ : 定数値が使用されます。 特殊文字を含む JSON パスは、['プロパティ名'] の形式でエスケープする必要があります。
ConstantValue OptionalJSON ファイル内の値ではなく、列に使用される定数値。
Transform Optional マッピング変換を使用してコンテンツに適用する必要がある変換。

JSON マッピングの例

[
  {"Column": "event_timestamp", "Properties": {"Path": "$.Timestamp"}}, 
  {"Column": "event_name",      "Properties": {"Path": "$.Event.Name"}}, 
  {"Column": "event_type",      "Properties": {"Path": "$.Event.Type"}}, 
  {"Column": "source_uri",      "Properties": {"Transform": "SourceLocation"}}, 
  {"Column": "source_line",     "Properties": {"Transform": "SourceLineNumber"}}, 
  {"Column": "event_time",      "Properties": {"Path": "$.Timestamp", "Transform": "DateTimeFromUnixMilliseconds"}}, 
  {"Column": "ingestion_time",  "Properties": {"ConstValue": "2021-01-01T10:32:00"}}, 
  {"Column": "full_record",     "Properties": {"Path": "$"}}
]

注意

上記のマッピングを制御コマンドの一部として指定すると、 .ingest JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2") 
  with 
  (
      format = "json", 
      ingestionMapping = 
      '['
        '{"Column": "column_a", "Properties": {"Path": "$.Obj.Property"}},'
        '{"Column": "column_b", "Properties": {"Path": "$.Property"}},'
        '{"Column": "custom_column", "Properties": {"Path": "$.[\'Property name with space\']"}}'
      ']'
  )

注意

上記のマッピングが 事前に作成 されている場合、コントロールコマンドで参照でき .ingest ます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="json", 
        ingestionMappingReference = "Mapping_Name"
    )

AVRO マッピング

ソースファイルが AVRO 形式の場合、AVRO ファイルの内容がテーブルにマップされます。 マップされているすべての列に有効なデータ型が指定されていない限り、テーブルはデータベースに存在している必要があります。 AVRO マッピングでマップされている列は、すべての既存でない列にデータ型が指定されていない限り、テーブルに存在する必要があります。

リスト内の各要素には、特定の列のマッピングが記述され、次のプロパティが含まれる場合があります。

プロパティ 説明
Field AVRO レコードのフィールドの名前。
Path を使用する代わりに Field 、必要に応じて AVRO レコードフィールドの内部部分を取得することもできます。 値は、AVRO レコードのルートからの JSON パス (AVRO レコード全体を示す JSON パス) を表し $ ます。 値が次の値で始まらない場合 $ : 定数値が使用されます。 特殊文字を含む JSON パスは、['プロパティ名'] の形式でエスケープする必要があります。 詳細については、以下のメモを参照してください。
ConstantValue OptionalAVRO ファイル内の値ではなく、列に使用される定数値。
Transform Optional サポートされている変換を使用してコンテンツに適用する必要がある変換。

メモ

注意

  • Field とを Path 一緒に使用することはできません。使用できるのは1つだけです。

以下の2つの選択肢は同じです。

[
  {"Column": "event_name", "Properties": {"Path": "$.EventName"}}
]
[
  {"Column": "event_name", "Properties": {"Field": "EventName"}}
]

AVRO マッピングの例

[
  {"Column": "event_timestamp", "Properties": {"Field": "Timestamp"}},
  {"Column": "event_name",      "Properties": {"Field": "Name"}},
  {"Column": "event_type",      "Properties": {"Field": "Type"}},
  {"Column": "event_time",      "Properties": {"Field": "Timestamp", "Transform": "DateTimeFromUnixMilliseconds"}}, 
  {"Column": "ingestion_time",  "Properties": {"ConstValue": "2021-01-01T10:32:00"}}, 
  {"Column": "full_record",     "Properties": {"Path": "$"}} 
]

注意

上記のマッピングを制御コマンドの一部として指定すると、 .ingest JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2") 
  with 
  (
      format = "AVRO", 
      ingestionMapping = 
      '['
        '{"Column": "column_a", "Properties": {"Field": "Field1"}},'
        '{"Column": "column_b", "Properties": {"Field": "$.[\'Field name with space\']"}}'
      ']'
  )

注意

上記のマッピングが 事前に作成 されている場合、コントロールコマンドで参照でき .ingest ます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="AVRO", 
        ingestionMappingReference = "Mapping_Name"
    )

Parquet のマッピング

ソースファイルが Parquet 形式の場合は、ファイルの内容がテーブルにマップされます。 マップされているすべての列に有効なデータ型が指定されていない限り、テーブルはデータベースに存在している必要があります。 Parquet マッピングでマップされている列は、すべての既存でない列にデータ型が指定されていない限り、テーブルに存在する必要があります。

リスト内の各要素には、特定の列のマッピングが記述され、次のプロパティが含まれる場合があります。

プロパティ 説明
Field Parquet レコード内のフィールドの名前。
Path を使用する代わりに、 Field 必要に応じて Parquet レコードフィールドの内部部分を取得することもできます。 値は、Parquet レコードのルートからの JSON パス (AVRO レコード全体を示す JSON パス) を表し $ ます。 値が次の値で始まらない場合 $ : 定数値が使用されます。 特殊文字を含む JSON パスは、['プロパティ名'] の形式でエスケープする必要があります。 詳細については、以下のメモを参照してください。
ConstantValue OptionalParquet ファイル内の値ではなく、列に使用される定数値。
Transform Optionalコンテンツに適用する必要がある 変換のマッピング
  • Field とを Path 一緒に使用することはできません。使用できるのは1つだけです。

以下の2つの選択肢は同じです。

[
  {"Column": "event_name", "Properties": {"Path": "$.EventName"}}
]
[
  {"Column": "event_name", "Properties": {"Field": "EventName"}}
]

Parquet マッピングの例

[
  {"Column": "event_timestamp", "Properties": {"Path": "$.Timestamp"}}, 
  {"Column": "event_name",      "Properties": {"Path": "$.Event.Name"}}, 
  {"Column": "event_type",      "Properties": {"Path": "$.Event.Type"}}, 
  {"Column": "event_time",      "Properties": {"Path": "$.Timestamp", "Transform": "DateTimeFromUnixMilliseconds"}}, 
  {"Column": "ingestion_time",  "Properties": {"ConstValue": "2021-01-01T10:32:00"}}, 
  {"Column": "full_record",     "Properties": {"Path": "$"}} 
]

注意

上記のマッピングを制御コマンドの一部として指定した場合 .ingest 、マッピングは JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2") 
  with 
  (
      format = "parquet", 
      ingestionMapping = 
      '['
        '{"Column": "column_a", "Properties": {"Path": "$.Field1.Subfield"}},'
        '{"Column": "column_b", "Properties": {"Path": "$.[\'Field name with space\']"}},'
      ']'
  )

注意

上記のマッピングが 事前に作成されている場合、コントロールコマンドで参照でき .ingest ます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="parquet", 
        ingestionMappingReference = "Mapping_Name"
    )

ORC のマッピング

ソースファイルが ORC 形式の場合は、ファイルの内容がテーブルにマップされます。 マップされているすべての列に有効なデータ型が指定されていない限り、テーブルはデータベースに存在している必要があります。 ORC マッピングでマップされている列は、すべての既存でない列にデータ型が指定されていない限り、テーブルに存在する必要があります。

リスト内の各要素には、特定の列のマッピングが記述され、次のプロパティが含まれる場合があります。

プロパティ 説明
Field ORC レコード内のフィールドの名前。
Path を使用する代わりに、 Field 必要に応じて ORC レコードフィールドの内部部分を取得することもできます。 値は、ORC レコードのルートからの JSON パス (ORC レコード全体を示す JSON パス) を表し $ ます。 値が次の値で始まらない場合 $ : 定数値が使用されます。 特殊文字を含む JSON パスは、['プロパティ名'] の形式でエスケープする必要があります。 詳細については、以下のメモを参照してください。
ConstantValue OptionalORC ファイル内の値ではなく、列に使用される定数値。
Transform Optionalコンテンツに適用する必要がある 変換のマッピング
  • Field とを Path 一緒に使用することはできません。使用できるのは1つだけです。

以下の2つの選択肢は同じです。

[
  {"Column": "event_name", "Properties": {"Path": "$.EventName"}}
]
[
  {"Column": "event_name", "Properties": {"Field": "EventName"}}
]

ORC mapping の例

[
  {"Column": "event_timestamp", "Properties": {"Path": "$.Timestamp"}}, 
  {"Column": "event_name",      "Properties": {"Path": "$.Event.Name"}}, 
  {"Column": "event_type",      "Properties": {"Path": "$.Event.Type"}}, 
  {"Column": "event_time",      "Properties": {"Path": "$.Timestamp", "Transform": "DateTimeFromUnixMilliseconds"}}, 
  {"Column": "ingestion_time",  "Properties": {"ConstValue": "2021-01-01T10:32:00"}}, 
  {"Column": "full_record",     "Properties": {"Path": "$"}} 
]

注意

上記のマッピングがコントロール コマンドの一部として .ingest 提供されている場合、JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2") 
  with 
  (
      format = "orc", 
      ingestionMapping = 
      '['
        '{"Column": "column_a", "Properties": {"Path": "$.Field1"}},'
        '{"Column": "column_b", "Properties": {"Path": "$.[\'Field name with space\']"}}'
      ']'
  )

注意

上記のマッピングが 事前に作成されている場合 は、コントロール コマンドで .ingest 参照できます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="orc", 
        ingestionMappingReference = "ORC_Mapping"
    )

W3CLOGFILE マッピング

ソース ファイルが W3CLOGFILE 形式の場合、ファイルの内容はテーブルにマップされます。 マップされた列に対して有効なデータ型が指定されていない限り、テーブルはデータベースに存在する必要があります。 W3CLOGFILE マッピングでマップされる列は、データ型が既存以外のすべての列に対して指定されていない限り、テーブルに存在する必要があります。

リスト内の各要素は、特定の列のマッピングを記述し、次のプロパティを含む場合があります。

プロパティ 説明
Field W3CLOGFILE エントリ名
ConstantValue (省略可能)W3CLOGFILE ファイル内の一部の値ではなく、列に使用される定数値。
Transform (省略可能) コンテンツに適用 する必要があるマッピング変換。

W3CLOGFILE マッピングの例

[
   {"Column": "Date",          "Properties": {"Field": "date"}},
   {"Column": "Time",          "Properties": {"Field": "time"}},
   {"Column": "IP",            "Properties": {"Field": "s-ip"}},
   {"Column": "ClientMethod",  "Properties": {"Field": "cs-method"}},
   {"Column": "ClientQuery",   "Properties": {"Field": "cs-uri-query"}},
   {"Column": "ServerPort",    "Properties": {"Field": "s-port"}},
   {"Column": "ClientIP",      "Properties": {"Field": "c-ip"}},
   {"Column": "UserAgent",     "Properties": {"Field": "cs(User-Agent)"}},
   {"Column": "Referer",       "Properties": {"Field": "cs(Referer)"}},
   {"Column": "Status",        "Properties": {"Field": "sc-status"}},
   {"Column": "ResponseBytes", "Properties": {"Field": "sc-bytes"}},
   {"Column": "RequestBytes",  "Properties": {"Field": "cs-bytes"}},
   {"Column": "TimeTaken",     "Properties": {"Field": "time-taken"}}
]

注意

W3CLOGFILE 形式でサポートされている変換は、 と SourceLineNumber のみです SourceLocation 。 上記のマッピングがコントロール コマンドの一部として .ingest 提供されている場合は、JSON 文字列としてシリアル化されます。

.ingest into Table123 (@"source1", @"source2") 
  with 
  (
      format = "w3clogfile", 
      ingestionMapping = 
      '['
         '{"Column": "column_a", "Properties": {"Field": "field1"}},' 
         '{"Column": "column_b", "Properties": {"Field": "field2"}}'
      ']'
  )

注意

上記のマッピングが 事前に作成されている場合 は、コントロール コマンドで .ingest 参照できます。

.ingest into Table123 (@"source1", @"source2")
    with 
    (
        format="w3clogfile", 
        ingestionMappingReference = "Mapping_Name"
    )

マッピング変換

一部のデータ形式マッピング (Parquet、JSON、AVRO) では、単純で便利な取り込み時間変換がサポートされています。 シナリオで取り込み時により複雑な処理が必要な場合は、Update ポリシーを使用します。これにより、KQL 式を使用して軽量処理を定義できます。

パス依存変換 説明 条件
PropertyBagArrayToDictionary プロパティの JSON 配列 (例: {events:[{"n1":"v1"},{"n2":"v2"}]}) をディクショナリに変換し、有効な JSON ドキュメント (例: {"n1":"v1","n2":"v2"}) にシリアル化します。 が使用されている場合にのみ Path 適用できます
SourceLocation データを提供したストレージ成果物の名前。文字列 (BLOB の "BaseUri" フィールドなど) を入力します。
SourceLineNumber そのストレージ成果物に対して相対的なオフセットを指定し、「long」と入力します ('1' から始め、新しいレコードごとにインクリメント)。
DateTimeFromUnixSeconds unix-time (1970-01-01 以降の秒) を表す数値を UTC 日時文字列に変換します
DateTimeFromUnixMilliseconds unix-time (1970-01-01 以降のミリ秒) を表す数値を UTC 日時文字列に変換します
DateTimeFromUnixMicroseconds unix-time (1970-01-01 以降のマイクロ秒) を表す数値を UTC 日時文字列に変換します
DateTimeFromUnixNanoseconds unix-time (1970-01-01 以降の nanoseconds) を表す数値を UTC 日時文字列に変換します