如何正确将Apache Avro嵌套字段摄取至Azure Data Explorer

• 从Blob存储摄取Event Hub Capture生成的Apache Avro格式数据到Azure Data Explorer时，$.Body这类顶层Avro键可正常映射，但$.Body.entityId这类Body内部的嵌套JSON键无法解析，对应列无数据
• UI配置中将「Nested Levels」调整为2时会触发无详细描述的报错，将层级调回1后报错无法消除，必须取消后重新启动配置流程
• 自动生成的列类型全部被判定为string，不符合业务预期
• 要求不使用更新策略类变通方案，直接在摄取阶段将Avro内部嵌套字段映射为表的独立列

现有配置信息 #

Avro文件Schema结构 #

Event Hub Capture生成的Avro文件基础结构如下：

{
  "SequenceNumber": "...",
  "Offset": "...",
  "EnqueuedTimeUTC": "...",
  "SystemProperties": "...",
  "Properties": "...",
  "Body": {
    "entityId": "...",
    "eventTime": "...",
    "messageId": "...",
    "data": "..."
  }
}

当前执行的KQL命令 #

// 建表命令
////////////////////////////////////////////////////////////
.create table ['test_table']  (['Body']:dynamic, ['entityId']:string)

// 创建摄取映射命令
////////////////////////////////////////////////////////////
.create table ['test_table'] ingestion apacheavro mapping 'test_table_mapping' '[{"column":"Body", "Properties":{"Path":"$.Body"}},{"column":"entityId", "Properties":{"Path":"$.Body.entityId"}}]'

// 执行数据摄取命令
///////////////////////////////////////////////////////////
.ingest async into table ['test_table'] (h'[SAS URL]') with (format='apacheavro',ingestionMappingReference='test_table_mapping',ingestionMappingType='apacheavro',tags="['503a2cfb-5b81-4c07-8658-639009870862']")

问题根因 #

Event Hub Capture生成Avro文件时，消息体Body字段默认以UTF-8编码的序列化JSON字符串/二进制格式存储，不是原生的Avro嵌套记录（Record）类型。ADX默认按原生Avro结构读取时，拿到的Body是纯字符串，无法直接通过JSON路径读取内部属性，这是嵌套字段映射失败、Nested Levels调整报错的核心原因。

操作步骤 #

• 修正Avro摄取映射配置：给Body字段的映射规则增加StringSerde转换声明，告知ADX该字段存储的是序列化JSON字符串，需要先反序列化为结构化动态对象再做路径解析。修正后的映射命令如下：

// 先删除原有错误映射
.drop table ['test_table'] ingestion mapping 'test_table_mapping'

// 创建正确的映射
.create table ['test_table'] ingestion apacheavro mapping 'test_table_mapping'
'[
    {"column":"Body", "Properties":{"Path":"$.Body", "Transform":"StringSerde"}},
    {"column":"entityId", "Properties":{"Path":"$.Body.entityId"}}
]'

• 若使用UI配置流程，无需手动调整Nested Levels参数，在字段映射配置页找到Body字段，将其转换规则选择为StringSerde，再手动补充嵌套字段的路径映射即可，不会触发无提示报错。
• 解决列类型识别异常问题：不要依赖UI自动生成的表结构，提前手动执行建表命令，根据业务数据给每个字段指定对应数据类型（比如时间字段指定为datetime、数值字段指定为long/real等），再关联映射执行摄取，就不会出现全字段被识别为string的问题。

StringSerde是ADX为Avro/Parquet等二进制格式摄取提供的原生转换能力，整个解析过程在摄取阶段完成，不需要额外配置更新策略，完全符合需求。

内容的提问来源于stack exchange，提问作者allrik