azure-kusto-data@5.0.1 摄入含'2_'模式的数据时出现重复且value字段为null的异常

遇到这种带有特定字符模式就触发异常的问题确实挺闹心的，尤其是直接在ADX查询里跑正常，但用客户端库就出问题的情况。结合你提供的信息，我来帮你拆解下可能的原因和对应的排查解决方向：

可能的核心原因推测 #

从现象来看，当device_key字段包含2_时就会生成一条value为null的重复记录，换字符后恢复正常，大概率是客户端库（azure-kusto-data@5.0.1）在处理文本数据时，把2_误判成了某种特殊的转义序列或分隔符，导致发送给ADX的请求中包含了异常的格式，最终ADX解析出两条记录（一条正常，一条异常）。

因为你提到无论是inline ingest还是streaming ingest都有这个问题，说明问题出在客户端对摄入数据的预处理环节，而非ADX端的摄入逻辑（毕竟直接在ADX跑查询没问题）。

具体排查与解决步骤 #

1. 检查客户端发送的原始请求内容

首先要确认客户端库在发送数据前是否对device_key字段做了意外修改。可以在代码里添加日志，输出要发送的完整摄入查询字符串，看看#ESSSAB2_T010JPK01KKP03这个字段是否被转义或截断了。比如在调用execute_kql_query前，打印完整的KQL语句：

# 在调用execute_kql_query前添加日志
ingest_query = f".ingest inline into table kpi_table <| 2025-03-13T22:06:00Z, kpi_inverter_production, #ESSSAB2, #ESSSAB2_T010JPK01KKP03, 0.0201"
logger.debug(f"完整摄入查询语句: {ingest_query}")
self.execute_kql_query(ingest_query)

如果发现2_被转成了其他内容（比如\2_或者被拆分），那就是客户端库的转义逻辑有问题。

2. 使用明确的摄入映射强制字段解析规则

ADX的自动解析有时候会因为数据中的特殊字符出现偏差，建议创建一个明确的CSV摄入映射，强制指定每个字段的位置、类型和分隔符，避免自动解析的歧义。

先在ADX中执行以下命令创建映射：

.create table kpi_table ingestion csv mapping "KpiTableCsvMapping"
'['
'   { "column": "server_timestamp", "DataType": "datetime", "Ordinal": 0 },'
'   { "column": "name", "DataType": "string", "Ordinal": 1 },'
'   { "column": "plant_id", "DataType": "string", "Ordinal": 2 },'
'   { "column": "device_key", "DataType": "string", "Ordinal": 3 },'
'   { "column": "value", "DataType": "real", "Ordinal": 4 }'
']'

然后在摄入查询中指定使用这个映射：

.ingest inline into table kpi_table with (format="csv", ingestionMappingReference="KpiTableCsvMapping") <|
2025-03-13T22:06:00Z, kpi_inverter_production, #ESSSAB2, #ESSSAB2_T010JPK01KKP03, 0.0201

这样ADX会严格按照映射规则解析每个字段，不会因为特殊字符产生误解析。

3. 升级azure-kusto-data到最新版本

这个很可能是客户端库的已知bug，建议你把azure-kusto-data升级到最新稳定版本，看看问题是否已经被修复：

pip install --upgrade azure-kusto-data

可以查看官方的版本更新日志，确认是否有修复过类似的文本转义或摄入解析问题。

4. 临时规避方案：对特殊字符进行转义

如果暂时无法升级库，可以尝试对device_key字段中的特殊字符进行手动转义，比如用引号把字符串字段包裹起来（CSV格式下，引号内的特殊字符会被当作普通文本处理）：
比如把摄入数据改成：

"2025-03-13T22:06:00Z", "kpi_inverter_production", "#ESSSAB2", "#ESSSAB2_T010JPK01KKP03", 0.0201

同时在摄入查询中指定CSV格式的引号规则，确保ADX能正确解析。

总结 #

这个问题的核心大概率是旧版本客户端库的文本处理bug，优先建议升级到最新版本；如果暂时无法升级，使用明确的摄入映射和手动转义特殊字符可以作为临时规避方案。如果升级后问题依然存在，建议在Azure的GitHub仓库提交issue，提供你的复现步骤和数据，让官方团队排查。

备注：内容来源于stack exchange，提问作者cperez-m