Elasticsearch 8.13.4 地理范围查询实战指南

在数字化地图的浩瀚海洋中，无论是寻找“附近的酒店”还是划定“电子围栏”，本质上都是一场对经纬度数据的精准围猎。当业务逻辑从简单的关键词搜索进阶到“我在哪里”的空间计算时，Elasticsearch 8.13.4 提供的地理查询能力便成为了那把劈开数据迷雾的利剑。

今天，我们将彻底拆解 Elasticsearch 的地理范围查询机制，从基础的圆半径计算到复杂的多边形过滤，带你掌握这门空间数据的艺术。

一、基石：Geo_point 的奥义

一切地理查询的前提，是正确的数据结构。在 Mapping 中，必须将位置字段显式定义为geo_point类型。这不仅是类型的声明，更是对空间索引算法的召唤。

关键细节：

存储格式：支持对象、数组或字符串。但请注意“经纬度”的顺序陷阱！在数组格式中，ES 严格遵循[经度(lon), 纬度(lat)]的顺序；而在字符串格式中，则是"纬度,经度"。一旦弄反，查询结果将南辕北辙。
编码原理：底层通过 Geohash 将二维坐标编码为一维字符串，实现高效的前缀匹配检索。

二、两大核心利器：半径与矩形

在 8.13.4 版本中，针对不同的业务场景，我们主要 wield 两把“神器”：geo_distance和geo_bounding_box。

1. 半径查询（geo_distance）：最常用的“附近”逻辑

这是外卖、打车软件的核心。它计算文档坐标与中心点的直线距离。

语法核心：指定圆心和半径。

GET/places/_search{"query":{"geo_distance":{"distance":"5km","location":{"lat":31.23,"lon":121.47}}}}

距离单位：支持km（公里）、mi（英里）等，无需换算，ES 自动处理。
计算模型：
- arc（默认）：球体计算，精度极高，适合长距离。
- plane：平面几何计算，速度极快，短距离内误差可忽略。

2. 矩形范围（geo_bounding_box）：地图视野的“矩形选框”

当用户在地图上拖拽出一个矩形视野时，用它最高效。它不计算球面距离，而是利用坐标的最大最小值进行过滤。

语法核心：定义左上角（top_left）和右下角（bottom_right）。

GET/places/_search{"query":{"geo_bounding_box":{"location":{"top_left":{"lat":31.3,"lon":121.5},"bottom_right":{"lat":31.1,"lon":121.3}}}}}

性能警示：若未开启索引优化，此查询默认采用内存计算（逐条判断点是否在框内），数据量大时可能成为瓶颈。建议在 Mapping 中配置为indexed模式以利用倒排索引加速。

三、进阶：多边形与排序的艺术

现实世界的边界往往是不规则的（如行政区、商圈）。此时，geo_shape和geo_polygon登场。

多边形查询：通过一系列经纬度顶点构成闭合区域。

"query":{"geo_polygon":{"location":{"points":[{"lat":31.1,"lon":121.1},{"lat":31.1,"lon":121.5},{"lat":31.5,"lon":121.5},{"lat":31.5,"lon":121.1},{"lat":31.1,"lon":121.1}]}}}

注意：首尾坐标必须相同以构成闭环。

距离排序（_geo_distance）：不仅要“在范围内”，还要“按距离排”。
```
"sort":[{"_geo_distance":{"location":{"lat":31.23,"lon":121.47},"order":"asc","unit":"km"}}]
```
这能轻松实现“离我最近的银行”这类需求。

四、避坑指南与最佳实践

拒绝 Text 类型：千万不要试图对text类型的字段做地理查询，那是全表扫描的灾难。必须使用keyword或geo_point。
Filter 是性能救星：地理查询通常是刚性过滤条件（在就是在，不在就是不在），不需要计算相关性得分（_score）。务必将地理查询放入bool查询的filter上下文中，利用 ES 的查询缓存机制，速度可提升数倍。
多边形性能陷阱：geo_shape的多边形顶点越多，计算越慢。复杂的边界（如海岸线）应提前简化顶点，或采用 Geohash Grid 聚合来降维打击。
空值处理：如果文档缺失 location 字段，默认会被忽略。如需特殊处理，需在 Mapping 中设置null_value。