数据映射

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

数据资源管理器支持不同类型的映射,包括 row-oriented(CSV、JSON、AVRO 和 W3CLOGFILE)以及 column-oriented(Parquet 和 ORC)。

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

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

映射可以是预先创建的,也可以是使用 参数从引入命令引用的。

无需指定映射即可进行引入(请参阅标识映射)。

CSV 映射

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

CSV 映射可以应用于分隔符分隔的所有格式:CSV、TSV、PSV、SCSV、SOHsv 和 TXT。 有关详细信息,请参阅支持的数据格式

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

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

注意

  • OrdinalConstantValue 互斥。
  • 对于 TXT 格式,只能映射 Ordinal0,因为文本被视为单列行。

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 into Table123 (@"source1", @"source2")
    with
    (
        format="csv",
        ingestionMappingReference = "MappingName"
    )

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

JSON 映射

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

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

属性 说明
Path 如果值以 $ 开头,说明它是字段的 JSON 路径,该字段将成为 JSON 文档中列的内容($ 是表示整个文档的 JSON 路径)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ["属性名称"]。 有关详细信息,请参阅 JSONPath 语法
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\']"}}'
      ']'
  )

注意

如果上述映射是预先创建的,可使用 控制命令引用它:

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

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

复制 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 路径应转义为 ["属性名称"]。 有关详细信息,请参阅 JSONPath 语法
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\']"}}'
      ']'
  )

注意

如果上述映射是预先创建的,可使用 控制命令引用它:

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

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

Parquet 映射

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

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

属性 说明
Field Parquet 记录中字段的名称。
Path 必要时可选择使用 Field,它允许获取 Parquet 记录字段的内部部分。 该值表示来自 Parquet 记录的根的 JSON 路径(表示整个 AVRO 记录的 JSON 路径为 $)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ["属性名称"]。 有关详细信息,请参阅 JSONPath 语法
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\']"}},'
      ']'
  )

注意

如果上述映射是预先创建的,可在 控制命令中引用它:

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

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

ORC 映射

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

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

属性 说明
Field ORC 记录中字段的名称。
Path 必要时可选择使用 Field,它允许获取 ORC 记录字段的内部部分。 该值表示来自 ORC 记录的根的 JSON 路径(表示整个 ORC 记录的 JSON 路径为 $)。 如果值不以 $ 开头,则使用常数值。 包含特殊字符的 JSON 路径应转义为 ["属性名称"]。 有关详细信息,请参阅 JSONPath 语法
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\']"}}'
      ']'
  )

注意

如果上述映射是预先创建的,可使用 控制命令引用它:

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

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

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

注意

如果上述映射是预先创建的,可使用 控制命令引用它:

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

注意

无需指定映射即可进行引入(请参阅标识映射)。

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

映射转换

部分数据格式映射(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 日期时间字符串

标识映射

无需指定 ingestionMappingingestionMappingReference 属性即可进行引入。 数据将使用从表的架构派生的标识数据映射进行映射。 表架构将保持不变。 应指定 format 属性。 (请参阅引入格式)。

格式类型 格式 映射逻辑
具有已定义列顺序的表格数据格式,如分隔符分隔或单行格式 CSV, TSV, TSVe, PSV, SCSV, Txt, SOHsv, Raw 所有表列都按其各自的顺序映射到数据列,并按它们在数据源中的显示顺序映射。 列数据类型取自表架构。
具有命名列或具有命名字段的记录的格式 JSON, Parquet, Avro, ApacheAvro, Orc, W3CLOGFILE 所有表列都映射到具有相同名称(区分大小写)的数据列或记录字段。 列数据类型取自表架构。

警告

表架构与数据结构(如列或字段数据类型、列或字段名称或数据编号)之间的任何不匹配都可能会导致数据被为空或不正确。