Elasticsearch 6.8.7批量索引报错：字段首尾含[.]致解析歧义

这个错误的核心原因非常明确：Elasticsearch 6.x及更高版本禁止字段名以.开头、结尾，或者包含连续的.——因为这种命名会和嵌套对象的路径解析规则冲突（比如嵌套字段user.name里的.用来表示层级），Elasticsearch无法明确解析这类字段的结构，因此抛出illegal_argument_exception。

为什么单条手动索引成功，但批量报错？ #

你遇到的“单条能成功、批量失败”的矛盾，大概率是以下两种情况之一：

• 你手动测试的单条文档没有包含违规字段名，但批量队列中存在其他带.开头/结尾的字段的文档；
• 手动索引时用的工具（比如Kibana Dev Tools）可能自动做了字段名修正，而Java客户端的Bulk Processor严格按照原始JSON结构提交，没有做自动处理。

具体排查与解决步骤 #

1. 全面检查批量文档的字段名

遍历所有待批量索引的JSONObject，重点排查是否存在以下类型的字段名：

• 以.开头（比如.internal_field）
• 以.结尾（比如user_email.）
• 包含连续.（比如user..name）

你可以在批量添加前加入一段校验修正逻辑，示例代码如下：

for (Map.Entry<String, JSONObject> entry : yourData.entrySet()) {
    JSONObject val = entry.getValue();
    // 遍历校验所有字段名
    Iterator<String> fieldIterator = val.keys();
    while (fieldIterator.hasNext()) {
        String field = fieldIterator.next();
        if (field.startsWith(".") || field.endsWith(".") || field.contains("..")) {
            // 修正违规字段：去除首尾的点，替换连续的点为单个点
            String correctedField = field.replaceAll("^\\.|\\.$", "").replaceAll("\\.\\.", ".");
            Object fieldValue = val.remove(field);
            val.put(correctedField, fieldValue);
        }
    }
    bulkProcessor.add(new IndexRequest("tweet").type("json").id(entry.getKey()).source(val, XContentType.JSON));
}

2. 排查JSON结构扁平化问题

如果你的JSONObject是从其他嵌套结构（比如多层Map）转换而来的，可能会出现扁平化的点分隔字段名（比如把{"user": {"name": "xxx"}}转换成了{"user.name": "xxx"}）。如果这类字段的开头/结尾刚好是.，就会触发错误。

解决方法是将扁平的点分隔字段重新转换为嵌套JSON结构，比如通过工具类把user.name这样的键还原成user对象下的name字段。

3. 提前创建索引映射，禁用动态映射

动态映射虽然方便，但容易在批量索引时因为字段命名问题触发异常。你可以手动创建tweet索引的映射，提前定义所有字段的类型，同时禁用动态映射避免意外：

PUT /tweet
{
  "mappings": {
    "json": {
      "dynamic": false,
      "properties": {
        "in_reply_to_status_id_str": {"type": "keyword"},
        "created_at": {"type": "date", "format": "EEE MMM dd HH:mm:ss ZZZZZ yyyy"},
        "source": {"type": "text"},
        "retweet_count": {"type": "integer"},
        // 其他字段依次按需定义...
      }
    }
  }
}

这样如果批量文档中出现映射未定义的违规字段，Elasticsearch会直接拒绝，方便你快速定位问题文档。

4. 小批量测试定位问题文档

你可以把批量队列拆分成小批次（比如每次10条）测试，快速定位到具体哪条文档包含违规字段，针对性处理。

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