Redis GEOSEARCH 查询附近地点的范围条件

Redis GEOSEARCH 适合解决“某个经纬度附近有哪些地点”这类范围查询。它查询的是由 GEOADD 写入的地理有序集合，可以用已有成员或经纬度作为中心，按圆形或矩形过滤，再决定排序、数量和是否返回距离、坐标。

官方地址：https://redis.io/

最小可用选择是：已有地点作中心就用 FROMMEMBER，外部坐标作中心就用 FROMLONLAT；圆形范围用 BYRADIUS，地图视口式矩形范围用 BYBOX。需要给业务排序或展示距离时，再加 ASC/DESC 与 WITHDIST。

先把地点写入 GEOSEARCH 能读懂的索引

GEOSEARCH 不会直接读取一张地点表，它读取的是 Redis 的地理位置有序集合。先用 GEOADD 把经度、纬度和成员名写入同一个 key，成员名可以是门店编号、仓库编号或服务点编号。

# 把三个服务点写入同一个地理索引，参数顺序是经度、纬度、成员名
redis-cli GEOADD store:geo 121.4737 31.2304 store:shanghai
redis-cli GEOADD store:geo 121.4998 31.2397 store:people-square
redis-cli GEOADD store:geo 121.4457 31.2176 store:west

# 先读取一个成员坐标，确认成员名和索引 key 的对应关系
redis-cli GEOPOS store:geo store:shanghai

这里的关键不是把经纬度拆成两个普通字段，而是让所有可被附近查询的成员进入同一个地理索引。经度在前、纬度在后，写入时顺序反了，查询结果也会偏离预期。

选择中心点与圆形或矩形范围

中心点有两种来源。FROMMEMBER 以索引中已有成员的位置为中心，适合“以某家门店为中心找附近门店”；FROMLONLAT 直接给经度和纬度，适合来自 GPS、地图选点或请求参数的坐标。

# 以已有门店为中心，在 5 千米圆形范围内按距离从近到远返回
redis-cli GEOSEARCH store:geo FROMMEMBER store:shanghai BYRADIUS 5 KM ASC WITHDIST

# 以请求坐标为中心，查询一个 8×6 千米的轴对齐矩形范围
redis-cli GEOSEARCH store:geo FROMLONLAT 121.4737 31.2304 BYBOX 8 6 KM ASC WITHDIST

BYRADIUS 和 BYBOX 不能同时使用。圆形更接近“距离中心不超过多少”的业务规则；矩形适合已经有地图视口、配送网格或经纬度外接框的场景。查询单位可以使用 M、KM、FT 或 MI，不要把数值和单位拆成两个业务层含义。

用排序、COUNT 和附加字段组织返回结果

默认返回全部匹配成员。面向列表接口时，通常应该显式设置上限，避免一个大范围把过多成员一次性交给应用层。ASC 表示近的在前，DESC 表示远的在前；COUNT 限制最多返回多少项。

# 最多返回 10 个最近地点，并同时返回距离，便于接口直接展示
redis-cli GEOSEARCH store:geo FROMLONLAT 121.4737 31.2304 BYRADIUS 10 KM ASC COUNT 10 WITHDIST

# COUNT ANY 可以更快凑够数量，但返回项不保证按距离有序
redis-cli GEOSEARCH store:geo FROMLONLAT 121.4737 31.2304 BYRADIUS 10 KM COUNT 10 ANY

需要在地图上画点时加 WITHCOORD；需要返回 Redis 的内部地理哈希时加 WITHHASH。一般业务列表优先使用 WITHDIST，因为距离是用户能理解、也最容易直接展示的字段。若使用 ANY，就不要在接口协议中暗示结果已经按最近距离排序。

几个容易混淆的边界

• 它不是道路距离。 GEOSEARCH 按地理坐标范围筛选，结果距离是空间距离近似，不包含道路绕行、单行道或实时路况。
• 坐标顺序要固定。 命令输入使用经度、纬度；接口层最好在字段名中明确 longitude 和 latitude，不要只传两个无名数字。
• 矩形不是圆形的别名。 BYBOX 是轴对齐矩形，不能直接当成“半径查询”的另一种写法。
• 大范围要控制上限。 官方文档给出的复杂度与过滤形状覆盖的网格区域有关，业务接口仍应通过范围、COUNT 和缓存策略控制结果规模。

常见问题

GEOSEARCH 能直接按门店名称模糊搜索吗？

不能。它的职责是地理范围筛选；门店名称模糊匹配应交给其他索引或应用层，再把候选结果与地理条件组合。

为什么加了 COUNT ANY 后结果顺序不稳定？

ANY 的目标是尽快收集足够数量，不保证返回结果按距离排序。如果调用方要求“最近的前 N 个”，应去掉 ANY 并显式使用 ASC。

小结

把地点集中写入地理有序集合后，GEOSEARCH 的选择可以归纳为四点：中心来自成员还是坐标，范围用圆形还是矩形，结果按近到远还是反向，最后是否需要数量上限和距离坐标。先确定这四个条件，再把命令封装进接口，查询语义会比“先查全量再在代码里筛选”更清晰。