字段发现未知形状 Circle - 如何解决此 Elasticsearch 异常

适用版本： 7.0-7.6

1. 错误异常的基本描述 #

Field [fieldName] found and unknown shape Circle 说明 Elasticsearch 已经识别到目标字段，但在把查询形状转换成 Lucene Query 时，遇到了当前实现不认识或不支持的 Circle 形状。

这通常不是字段不存在，而是 传入了当前版本不支持的几何类型。

常见现象 #

• geo_shape 查询直接返回 400 或 QueryShardException。
• 同一字段用 polygon、envelope 等形状可以执行，但换成 circle 就失败。
• 多见于旧版本 Elasticsearch 或把其他地理库的 circle 表示直接塞进查询。

2. 为什么会发生这个错误 #

• 当前 Elasticsearch 版本不支持将 Circle 作为查询形状。
• 请求中的 geo 形状类型写成了 Circle，但版本只支持 point、polygon、envelope 等。
• 使用第三方客户端或上层平台生成了不兼容的 circle 语法。
• 从新版本示例复制了 circle 查询，到旧版本集群上运行。

3. 排查步骤 #

1. 检查请求体中的 geo 形状 type 是否为 circle。
2. 确认当前 Elasticsearch 版本对 geo_shape 查询支持的形状列表。
3. 用 polygon 或 envelope 替代 circle 做最小复现，确认字段 mapping 本身没有问题。
4. 如果请求由 SDK 生成，打印最终 JSON，确认不是客户端自动转换成了 circle。
5. 检查是否存在版本不匹配的示例、插件或中间层。

4. 修复建议 #

• 在不支持 circle 的版本中，将圆形近似转换为 polygon。
• 如果业务依赖原生 circle 支持，升级到明确支持该能力的版本。
• 为 geo 查询生成逻辑增加版本判断，避免向旧集群下发不受支持的形状。
• 保持 geo_shape 字段和查询形状格式与当前版本文档一致。

5. 小结 #

这个异常的关键不是字段丢失，而是 当前查询形状 Circle 超出了该版本 geo_shape 处理器的支持范围。修复思路通常是换形状或升级版本。

相关错误 #

• field-fieldname-found-and-unknown-shape：字段发现未知 shape
• field-name-found-and-unsupported-shape-linearring：字段不支持 LinearRing
• geo-polygon-unexpected-token-type-token-name：geo_polygon 中出现非法 token

附：日志上下文 #

下面保留当前页面中的源码或日志片段，便于继续结合异常调用栈定位问题：

this.relation = relation;
 }  @Override
 public Query visit(Circle circle) {
 throw new QueryShardException(context; "Field [" + fieldName + "] found and unknown shape Circle");
 }  @Override
 public Query visit(GeometryCollectioncollection) {
 BooleanQuery.Builder bqb = new BooleanQuery.Builder();