使用Azure Data Explorer Java SDK内联摄入的参数指定与报错问题

1. 摄入报错核心原因 #

你遇到的Stream_WrongNumberOfFields报错，本质是错误地将KQL查询参数声明（declare query_parameters语句）放到了.ingest inline命令的<|分隔符之后。

.ingest inline语法规则中，<|是数据源与命令逻辑的分隔线，它后面的所有内容都会被ADX当作待摄入的CSV数据解析。你写的4行declare语句会被识别为4条CSV记录，每条仅包含1个字段（比如整行declare query_parameters(field1:string);被当作单个字段），但最后一行[field1, field2, field3, timeField]被解析为4个字段，前后字段数不一致，直接触发字段不匹配错误。

即便把declare移到<|后的前部，只要还在数据源区域内，ADX依然会将其视为数据处理，报错不会消失。

2. Web UI中正确的内联摄入写法 #

移除<|后的declare语句，直接传入结构化CSV数据。若需参数化，不要在KQL中写declare，而是通过客户端绑定参数：

.ingest inline into table MyTable
with (
    format = "csv",
    ingestionMappingReference = "MyMapping"
) <|
@field1, @field2, @field3, @timeField

这里的@field1等是参数占位符，具体值需在执行时从客户端传入，而非在KQL内声明。

3. ADX Java SDK内联摄入并指定查询参数的方法 #

使用ADX Java SDK时，无需在KQL命令中编写declare语句，直接通过ClientRequestProperties类设置查询参数，步骤如下：

步骤1：构建参数化摄入命令 #

编写不带declare的内联摄入KQL，用@参数名作为占位符：

String ingestCommand = ".ingest inline into table MyTable " +
                       "with (format = 'csv', ingestionMappingReference = 'MyMapping') <| " +
                       "@field1, @field2, @field3, @timeField";

步骤2：绑定参数值 #

创建ClientRequestProperties实例，添加参数键值对：

ClientRequestProperties properties = new ClientRequestProperties();
properties.setParameter("field1", "value1");
properties.setParameter("field2", "value2");
properties.setParameter("field3", "value3");
properties.setParameter("timeField", "2024-05-20T12:00:00Z");

步骤3：执行摄入命令 #

通过已初始化的ADX客户端执行命令，传入参数配置：

// 假设已完成KustoClient实例初始化
client.executeCommand(databaseName, ingestCommand, properties);

额外注意事项 #

• 确保MyMapping的字段映射规则与CSV字段顺序、参数类型完全匹配，比如timeField需符合ADX的datetime格式要求。
• 若需摄入多条数据，在<|后用换行分隔每条CSV记录，对应设置多组参数即可，示例：

  String ingestCommand = ".ingest inline into table MyTable " +
                         "with (format = 'csv', ingestionMappingReference = 'MyMapping') <| " +
                         "@field1_1, @field2_1, @field3_1, @timeField_1\n" +
                         "@field1_2, @field2_2, @field3_2, @timeField_2";
  

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