Spring Data Elasticsearch中@Id字段用FieldType.keyword引发IllegalArgumentException

嘿，我完全懂你碰到的这个坑！带连字符的UUID用term查询死活匹配不到，其实问题大多出在字段的映射配置上——咱们结合你的代码来一步步解决。

先看你的实体类：

@Document(indexName = "indexName", type = "metadata")
public class EsMetadata {
    @Id
    @NonNull
    @Field(type = FieldType.keyword)
    String metadataId;
    @NonNull
    @Field(type = FieldType.keyword)
    String assetId;
}

你可能会纳闷：明明已经把字段设为keyword类型了，为啥还是搜不到？核心原因有两个：

1. 索引自动创建时的动态映射坑：如果你的索引是Elasticsearch自动创建的，有时候会忽略你的注解配置，把这些UUID字段默认映射成text类型。而text类型会把带连字符的UUID拆分成多个词项（比如把a1b2-c3d4拆成a1b2和c3d4），term查询是精确匹配单个词项，自然找不到完整的UUID。
2. 旧映射未更新：如果是先创建了索引，之后才修改实体类的注解，旧的映射不会自动覆盖，字段类型还是保持之前的配置。

具体解决方案 #

方案一：检查并修正字段映射（适合已有数据的场景）

首先用ES API检查当前索引的映射：

GET indexName/_mapping/metadata

如果返回结果里，metadataId和assetId是text类型（可能还附带keyword子字段），那咱们需要更新映射来添加明确的keyword子字段：

PUT indexName/_mapping/metadata
{
  "properties": {
    "metadataId": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256
        }
      }
    },
    "assetId": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256
        }
      }
    }
  }
}

之后查询时，要指定使用.keyword子字段来做精确匹配：

GET indexName/_search
{
  "query": {
    "term": {
      "metadataId.keyword": "你的带连字符UUID"
    }
  }
}

方案二：重新创建索引（适合无数据或可重新导入数据的场景）

如果你的索引还没有重要数据，或者可以重新导入数据，那直接删除旧索引，然后让Spring Data Elasticsearch根据你的实体类注解重新创建索引。这时候字段会被正确映射为keyword类型，之后直接用term查询字段本身就能匹配到：

GET indexName/_search
{
  "query": {
    "term": {
      "metadataId": "你的带连字符UUID"
    }
  }
}

小Tips #

• 尽量手动创建索引并配置映射，不要依赖Elasticsearch的自动映射，避免这类意想不到的问题。
• 对于UUID这种需要精确匹配的字段，keyword类型是最优选择，它会完整存储整个字符串作为单个词项，完美适配term查询的精确匹配需求。

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