引入映射
适用于:✅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 日期/时间字符串。 | 适用于 JSON 、Parquet 、AVRO 和 ORC 映射类型。 |
DateTimeFromUnixMilliseconds | 将表示 unix 时间的数字(从 1970-01-01 开始的毫秒数)转换为 UTC 日期/时间字符串。 | 适用于 JSON 、Parquet 、AVRO 和 ORC 映射类型。 |
DateTimeFromUnixMicroseconds | 将表示 unix 时间的数字(从 1970-01-01 开始的微秒数)转换为 UTC 日期/时间字符串。 | 适用于 JSON 、Parquet 、AVRO 和 ORC 映射类型。 |
DateTimeFromUnixNanoseconds | 将表示 unix 时间的数字(从 1970-01-01 开始的纳秒数)转换为 UTC 日期/时间字符串。 | 适用于 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== |