你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

引入映射

适用于：✅Microsoft Fabric✅Azure 数据资源管理器

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

数据资源管理器支持不同类型的映射，包括行导向（CSV、JSON、AVRO 和 W3CLOGFILE）以及列导向（Parquet 和 ORC）。

引入映射可以是预先创建的，也可以是使用 ingestionMappingReference 参数从引入命令引用的。 无需指定映射即可进行引入。 有关详细信息，请参阅标识映射。

映射列表中的每个元素都由以下三个字段构成：

properties	必选	说明
列	✔️	表中的目标列名称。
Datatype		当表中不存在映射列时，用于创建该列的数据类型。
属性		属性包，包含特定于每个映射的属性，如每个特定映射类型页面所述。

重要

对于排队引入：

• 如果映射中引用的表不存在于数据库中，则会自动创建该表，前提是为所有列指定了有效的数据类型。
• 如果映射中引用的某个列在表中不存在，则在首次为该列引入数据时，会自动将该列添加为表中的最后一列，前提是为该列指定了有效的数据类型。 若要向映射添加新列，请使用 .alter ingestion mapping 命令。
• 使用引入属性对数据进行批处理。 使用的引入映射属性越不同（例如不同的 ConstValue 值），引入就越分散，这可能会导致性能下降。

支持的映射类型

下表定义了在引入或查询特定格式的外部数据时要使用的映射类型。

数据格式	映射类型
CSV	CSV 映射
TSV	CSV 映射
TSVe	CSV 映射
PSV	CSV 映射
SCSV	CSV 映射
SOHsv	CSV 映射
TXT	CSV 映射
RAW	CSV 映射
JSON	JSON 映射
AVRO	AVRO 映射
APACHEAVRO	AVRO 映射
Parquet	Parquet 映射
ORC	ORC 映射
W3CLOGFILE	W3CLOGFILE 映射

标识映射

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

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

警告

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

映射转换

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

路径依赖转换	说明	Conditions
PropertyBagArrayToDictionary	将属性的 JSON 数组（例如 {events:[{"n1":"v1"},{"n2":"v2"}]}）转换为字典，并将其序列化为有效的 JSON 文档（例如 {"n1":"v1","n2":"v2"}）。	适用于 JSON、Parquet、AVRO 和 ORC 映射类型。
SourceLocation	提供数据的存储项目的名称，类型 string（例如 blob 的“BaseUri”字段）。	适用于 CSV、JSON、Parquet、AVRO、ORC 和 W3CLOGFILE 映射类型。
SourceLineNumber	相对于该存储项目的偏移量，类型 long（从“1”开始，按每条新记录递增）。	适用于 CSV、JSON、Parquet、AVRO、ORC 和 W3CLOGFILE 映射类型。
DateTimeFromUnixSeconds	将表示 unix 时间的数字（从 1970-01-01 开始的秒数）转换为 UTC 日期/时间字符串。	适用于 CSV、JSON、Parquet、AVRO 和 ORC 映射类型。
DateTimeFromUnixMilliseconds	将表示 unix 时间的数字（从 1970-01-01 开始的毫秒数）转换为 UTC 日期/时间字符串。	适用于 CSV、JSON、Parquet、AVRO 和 ORC 映射类型。
DateTimeFromUnixMicroseconds	将表示 unix 时间的数字（从 1970-01-01 开始的微秒数）转换为 UTC 日期/时间字符串。	适用于 CSV、JSON、Parquet、AVRO 和 ORC 映射类型。
DateTimeFromUnixNanoseconds	将表示 unix 时间的数字（从 1970-01-01 开始的纳秒数）转换为 UTC 日期/时间字符串。	适用于 CSV、JSON、Parquet、AVRO 和 ORC 映射类型。
DropMappedFields	将 JSON 文档中的对象映射到列，并删除已被其他列映射引用的任何嵌套字段。	适用于 JSON、Parquet、AVRO 和 ORC 映射类型。
BytesAsBase64	将数据视为字节数组，并将其转换为 base64 编码的字符串。	适用于 AVRO 映射类型。 对于 ApacheAvro 格式，已映射数据字段的架构类型应为 bytes 或 fixed Avro 类型。 对于 Avro 格式，字段应为包含 [0-255] 范围内的字节值的数组。 如果数据不代表有效的字节数组，则引入 null。

映射转换示例

DropMappedFields 转换：

给定以下 JSON 内容：

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "EventName": "CustomEvent",
        "Revenue": 0.456
    }
}

以下数据映射将整个 Props 对象映射到动态列 Props，同时排除已映射的列（Props.EventName 已映射到列 EventName，因此被排除）。

[
    { "Column": "Time", "Properties": { "Path": "$.Time" } },
    { "Column": "EventName", "Properties": { "Path": "$.Props.EventName" } },
    { "Column": "Props", "Properties": { "Path": "$.Props", "Transform":"DropMappedFields" } },
]

引入的数据如下所示：

时间	EventName	属性
2012-01-15T10:45	CustomEvent	{"Revenue": 0.456}

BytesAsBase64 转换

给定以下 AVRO 文件内容：

{
    "Time": "2012-01-15T10:45",
    "Props": {
        "id": [227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52]
    }
}

以下数据映射将 ID 列映射两次，不管是否进行转换。

[
    { "Column": "ID", "Properties": { "Path": "$.props.id" } },
    { "Column": "Base64EncodedId", "Properties": { "Path": "$.props.id", "Transform":"BytesAsBase64" } },
]

引入的数据如下所示：

ID	Base64EncodedId
[227,131,34,92,28,91,65,72,134,138,9,133,51,45,104,52]	44MiXBxbQUiGigmFMy1oNA==