适用版本： 6.8-8.x
1. 错误异常的基本描述 #
failed to find geo_shape field [fieldName] 是 Elasticsearch 在执行 geo_shape 类型查询时抛出的 QueryShardException。该错误表示查询中引用的字段在目标索引的 mapping 中不存在，或者该字段的类型不是 geo_shape。
常见现象 #
- 执行
geo_shape查询、空间相交查询（intersects）、多边形过滤（within、contains、disjoint）时直接返回400错误。 - 同一个查询在部分索引上执行成功，在另一些索引上失败，常见于跨索引联合查询场景。
- 使用索引通配符（如
logs-*）或索引别名查询时，部分无此字段的索引触发异常。 - Kibana 地图可视化组件加载失败，或自定义地理空间查询在开发环境正常，上线后报错。
错误响应示例：
{"error": {"root_cause": [{"type": "query_shard_exception", "reason": "failed to find geo_shape field [location]"}], "type": "search_phase_execution_exception", "reason": "all shards failed"}, "status": 400}
2. 为什么会发生这个错误 #
该异常的根本原因是查询所需的 geo_shape 字段映射在目标索引中不存在，而非几何数据本身的格式问题。
常见原因包括：
- 字段名拼写错误：DSL 中引用的字段名与 mapping 中定义的不一致，包括大小写、下划线、多层嵌套路径错误。
- 字段类型不符：目标字段存在，但类型为
geo_point、object或text，而非geo_shape。 - 索引缺少 mapping：目标索引尚未为该字段建立
geo_shape类型的映射，或者索引是在没有对应模板的情况下创建的。 - 跨索引查询命中无字段索引：使用通配符或别名查询时，某些索引没有该字段，导致整体查询失败。
- 索引模板版本不一致：模板升级后，新旧索引对空间字段的定义不一致，部分老索引缺少
geo_shape字段。 - 动态 mapping 未生效：写入的文档中几何数据格式不正确，导致 Elasticsearch 未能自动推断出
geo_shape类型。
3. 如何排查和解决这个异常 #
建议按以下顺序进行排查：
- 确认报错的具体字段名和索引范围：从错误响应中提取
fieldName和请求的索引列表。 - 检查目标索引的 mapping：使用
GET /<index>/_mapping确认字段是否存在，以及字段类型是否为geo_shape。 - 确认查询命中的全部索引：如果使用了通配符或别名，列出所有被命中的索引，逐一检查其 mapping。
- 检查索引模板：使用
GET /_index_template/<template_name>确认模板中是否包含该geo_shape字段的定义。
排查注意事项 #
- 不要只关注报错索引，还要检查同一查询模式下的所有索引，避免"修复一个，另一个又报错"。
- 在跨索引场景下，优先考虑使用
ignore_unmapped参数。
4. 如何解决这个错误 #
方案一：修正查询中的字段路径 #
确认字段名拼写和嵌套路径是否正确。若字段位于嵌套对象中，需使用完整路径，如 geometry.coordinates。
{"query": {"geo_shape": {"location": {"shape": {"type": "envelope", "coordinates": [[-10, 10], [10, -10]]}, "relation": "intersects"}}}}
方案二：为目标索引添加 geo_shape mapping #
PUT /your_index/_mapping
{"properties": {"location": {"type": "geo_shape"}}}
注意：已有数据且未定义 mapping 的索引，添加 mapping 后需重新索引数据才能生效。
方案三：使用 ignore_unmapped 忽略无字段索引 #
{
"query": {
"geo_shape": {
"location": {
"shape": {"type": "envelope", "coordinates": [[-10, 10], [10, -10]]},
"ignore_unmapped": true
}
}
}
}
方案四：统一索引模板 #
PUT /_index_template/geo_shape_template
{
"index_patterns": ["logs-*"],
"template": {
"mappings": {
"properties": {"location": {"type": "geo_shape"}}
}
}
}
后续注意事项 #
- 为空间字段查询建立标准化 mapping 模板，确保所有相关索引都包含必要的
geo_shape字段定义。 - 在跨索引查询场景中，优先使用
ignore_unmapped: true，避免单索引缺失字段导致整体查询失败。 - 对几何数据的写入格式进行校验，确保
geo_shape字段能被正确推断和索引。 - 定期审查索引模板的版本一致性，特别是在滚动升级或模板变更之后。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群 mapping 状态、索引模板配置、跨索引查询失败趋势。
- INFINI Gateway 适合部署在 Elasticsearch 前面做请求观测、DSL 审计和流量治理。
5. 小结 #
failed to find geo_shape field [fieldName] 的定位思路非常明确：查询引用的 geo_shape 映射在目标索引中不存在。排查时应优先检查 mapping 定义和查询命中的索引范围，而非文档数据本身。通过统一索引模板、合理使用 ignore_unmapped 参数，以及借助 INFINI Console 和 INFINI Gateway 进行持续观测，可以有效避免此类异常反复出现。
相关错误 #
附：日志上下文 #
final MappedFieldType fieldType = context.fieldMapper(fieldName);
if (fieldType == null) {
if (ignoreUnmapped) {
return new MatchNoDocsQuery();
} else {
throw new QueryShardException(context, "failed to find geo_shape field [" + fieldName + "]");
}
} else if (fieldType.typeName().equals(BaseGeoShapeFieldMapper.CONTENT_TYPE) == false) {
throw new QueryShardException(context,
"Field [" + fieldName + "] is not of type [geo_shape] but of type [" + fieldType.typeName() + "]");
}
