数据映射

数据映射在引入过程中使用,将传入数据映射到表中的列。

Kusto 支持不同类型的映射,包括 row-oriented(CSV、JSON、AVRO 和 W3CLOGFILE)和 column-oriented(Parquet 和 ORC)。

映射列表中的每个元素都由以下三个属性构成:

属性 说明
Column 表中的目标列名称
Datatype (可选)数据类型,如果表中不存在映射列,则使用该数据类型创建映射列
Properties (可选)属性包,包含特定于每个映射的属性,如下一节中所述。

所有映射都可以 预先创建 ,并可使用参数从引入命令引用

CSV 映射

当源文件是 CSV(或任何以分隔符分隔的格式),且其架构与当前表架构不匹配时,CSV 映射会从文件架构映射到表架构。 如果此表不存在于 Azure 数据资源管理器中,则将根据此映射创建该表。 如果表中缺少映射中的某些字段,将添加这些字段。

CSV 映射可以应用于所有分隔符分隔的格式:CSV、TSV、PSV、SCSV 和 SOHsv。

列表中的每个元素都描述特定列的映射,并且可能包含以下属性:

属性 说明
Ordinal CSV 中的列顺序号。
ConstantValue (可选)要用于列而非 CSV 文件内某个值的常数值。

注意

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}}'
        ']'
    )

注意

如果上面的映射是 预先创建 的,则可以在 control 命令中引用它

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

JSON 映射

当源文件采用 JSON 格式时,文件内容会映射到表。 表必须存在于数据库中,除非为映射的所有列指定了有效的数据类型。 在 JSON 映射中,被映射的列必须存在于表中,除非为所有不存在的列指定了数据类型。

列表中的每个元素都描述特定列的映射,并且可能包含以下属性:

属性 说明
Path 如果值以 $ 开头,说明它是字段的 JSON 路径,该字段将成为 JSON 文档中列的内容($ 是表示整个文档的 JSON 路径)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ["属性名称"]。
ConstantValue (可选)要用于列而非 JSON 文件内某个值的常数值。
Transform (可选)应通过映射转换应用于内容的转换。

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\']"}}'
      ']'
  )

注意

如果上面的映射是 预先创建 的,则可以在 control 命令中引用它

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

复制 JSON 映射的示例

可使用以下过程复制现有表的 JSON 映射,并使用相同的映射来创建新表:

  1. 在要复制其映射的表上运行以下命令:

    .show table TABLENAME ingestion json mappings 
    | extend formatted_mapping = strcat("'",replace_string(Mapping, "'", "\\'"),"'") 
    | project formatted_mapping
    
  2. 使用上述命令的输出创建具有相同映射的新表:

    .create table TABLENAME ingestion json mapping "TABLENAME_Mapping" RESULT_OF_ABOVE_CMD
    

AVRO 映射

当源文件采用 AVRO 格式时,AVRO 文件内容会映射到表。 表必须存在于数据库中,除非为映射的所有列指定了有效的数据类型。 在 AVRO 映射中,被映射的列必须存在于表中,除非为所有不存在的列指定了数据类型。

列表中的每个元素都描述特定列的映射,并且可能包含以下属性:

属性 说明
Field AVRO 记录中字段的名称。
Path 必要时可选择使用 Field,它允许获取 AVRO 记录字段的内部部分。 该值表示来自 AVRO 记录的根的 JSON 路径(表示整个 AVRO 记录的 JSON 路径为 $)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ["属性名称"]。 有关详细信息,请参阅以下备注。
ConstantValue (可选)要用于列而非 AVRO 文件内某个值的常数值。
Transform (可选)应通过支持的转换应用于内容的转换。

说明

注意

  • FieldPath 不能一起使用;只能使用其中一个。

以下两种替代方法是等效的:

[
  {"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\']"}}'
      ']'
  )

注意

如果上面的映射是 预先创建 的,则可以在 control 命令中引用它

.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 (可选)要用于列而非 Parquet 文件内某个值的常数值。
Transform (可选)应该应用于内容的映射转换
  • FieldPath 不能一起使用,只能使用其中一个。

以下两种替代方法是等效的:

[
  {"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\']"}},'
      ']'
  )

注意

如果上面的映射是 预先创建的,则可以在 control 命令中引用它

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

ORC 映射

当源文件采用 ORC 格式时,文件内容会映射到表。 表必须存在于数据库中,除非为映射的所有列指定了有效的数据类型。 在 ORC 映射中,被映射的列必须存在于表中,除非为所有不存在的列指定了数据类型。

列表中的每个元素都描述特定列的映射,并且可能包含以下属性:

属性 说明
Field ORC 记录中字段的名称。
Path 必要时可选择使用 Field,它允许获取 ORC 记录字段的内部部分。 该值表示来自 ORC 记录的根的 JSON 路径(表示整个 ORC 记录的 JSON 路径为 $)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ['Property Name']。 有关详细信息,请参阅以下备注。
ConstantValue (可选)要用于列而非 ORC 文件内某个值的常数值。
Transform (可选)应该应用于内容的映射转换
  • FieldPath 不能一起使用,只能使用其中一个。

以下两种替代方法是等效的:

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

ORC 映射示例

[
  {"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\']"}}'
      ']'
  )

注意

预先创建上述映射 后, 可以在 control 命令 中引用该映射:

.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 格式转换为:SourceLineNumberSourceLocation。 当上述映射作为 .ingest 控制命令的一部分提供时,它将被序列化为 JSON 字符串。

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

注意

预先创建上述映射 后, 可以在 control 命令 中引用该映射:

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

映射转换

部分数据格式映射(Parquet、JSON 和 AVRO)支持简单有用的引入时间转换。 如果在引入时需要进行更复杂的处理,可使用更新策略,该策略允许使用 KQL 表达式定义轻型处理。

路径依赖转换 说明 Conditions
PropertyBagArrayToDictionary 将属性的 JSON 数组(例如 {events:[{"n1":"v1"},{"n2":"v2"}]})转换为字典,并将其序列化为有效的 JSON 文档(例如 {"n1":"v1","n2":"v2"})。 仅当使用 Path 时才能应用
SourceLocation 提供数据的存储项目的名称,类型 string(例如 blob 的“BaseUri”字段)。
SourceLineNumber 相对于该存储项目的偏移量,类型 long(从“1”开始,按每条新记录递增)。
DateTimeFromUnixSeconds 将表示 unix 时间的数字(从 1970-01-01 开始的秒数)转换为 UTC 日期时间字符串
DateTimeFromUnixMilliseconds 将表示 unix 时间的数字(从 1970-01-01 开始的毫秒数)转换为 UTC 日期时间字符串
DateTimeFromUnixMicroseconds 将表示 unix 时间的数字(从 1970-01-01 开始的微秒数)转换为 UTC 日期时间字符串
DateTimeFromUnixNanoseconds 将表示 unix 时间的数字(从 1970-01-01 开始的纳秒数)转换为 UTC 日期时间字符串