Redis GEOSEARCH 怎样按距离和形状筛选位置

如果 Redis 里已经用 GEOADD 保存了门店、设备或配送点，下一步通常不是再写一套距离计算，而是直接使用 GEOSEARCH。它能以成员或经纬度作为中心，用 BYRADIUS 查询圆形范围，用 BYBOX 查询矩形范围，再用 WITHDIST、WITHCOORD 和排序参数补齐列表所需的信息。

官方地址：https://redis.io/docs/latest/commands/geosearch/

实际项目里可以先用 BYRADIUS 解决“附近多少公里”，再用 BYBOX 解决“落在这个宽高框内”。需要展示距离时加 WITHDIST，需要回显经纬度时加 WITHCOORD；不要把 COUNT ANY 当成精确的最近排序。

先准备一组可复现的地理数据

GEOSEARCH 查询的是 Redis 的地理索引。下面用一个城市中心附近的门店集合做小实验，成员名只是示例数据，重点是经度在前、纬度在后。

# 写入四个测试点；参数顺序固定为 经度 纬度 成员名
redis-cli GEOADD shop:geo \
  116.397128 39.916527 "中心店" \
  116.407526 39.904030 "南门店" \
  116.365000 39.930000 "西区店" \
  116.450000 39.950000 "东区店"

# 先读取成员，确认测试索引里已经有样本数据
redis-cli ZRANGE shop:geo 0 -1

这里的 shop:geo 是地理索引键。生产代码里建议把业务类型写进键名，并为测试使用独立键，避免调试数据和真实门店混在一起。

用 BYRADIUS 查询圆形范围

“以中心点为圆心，查 5 千米以内的门店”对应 FROMLONLAT 加 BYRADIUS。单位可以写 M、KM、FT 或 MI，查询中心的参数顺序仍然是经度、纬度。

# 以中心店坐标附近的经纬度为中心，查询 5 千米圆形区域
redis-cli GEOSEARCH shop:geo \
  FROMLONLAT 116.397128 39.916527 \
  BYRADIUS 5 KM \
  ASC WITHDIST WITHCOORD

ASC 会让结果按距离从近到远排列；WITHDIST 给每个成员附带距离，单位与 BYRADIUS 后面的单位一致；WITHCOORD 再附带成员原本的经纬度。返回值因此不再只是成员名，而是“成员、距离、坐标”的组合结构。

如果业务只需要成员名，可以去掉两个 WITH 选项；如果要展示“最近的前三家”，可以继续追加 COUNT 3，但保留 ASC，否则数量限制和排序目标并不一致。

用 BYBOX 查询矩形范围

门店围栏、配送网格或地图视口更适合矩形过滤。此时把 BYRADIUS 换成 BYBOX width height unit，宽和高描述的是矩形的两条边，中心点仍由 FROMLONLAT 或 FROMMEMBER 提供。

# 以中心点为矩形中心，按宽 12 千米、高 8 千米筛选
redis-cli GEOSEARCH shop:geo \
  FROMLONLAT 116.397128 39.916527 \
  BYBOX 12 8 KM \
  ASC WITHDIST WITHCOORD

圆形和矩形不是同一种边界：BYRADIUS 5 KM 表示距离中心不超过半径的区域，BYBOX 12 8 KM 表示宽高分别为 12 和 8 千米的框。不要把“5 千米半径”机械换成“10 千米宽高”后认为两次结果一定相同，它们的角点覆盖范围不同。

把排序、数量和返回字段组合起来

常用组合可以按“边界、排序、数量、字段”四层理解：

# 只取最近的两条，并保留距离；适合“最近门店”列表
redis-cli GEOSEARCH shop:geo \
  FROMMEMBER "中心店" \
  BYRADIUS 5 KM \
  ASC COUNT 2 WITHDIST

# 只追求快速拿到若干候选；不要把它当作严格最近排序
redis-cli GEOSEARCH shop:geo \
  FROMMEMBER "中心店" \
  BYBOX 20 20 KM \
  COUNT 10 ANY WITHCOORD

官方命令说明明确区分了普通 COUNT 和 ANY：不带 ANY 时，Redis 会为匹配区域投入更多工作来排序；带上 ANY 后可以更快拿到数量，但结果可能不是距离最近的一组。因此，配送计价、最近门店和排序分页不要使用 ANY，而只把它用于“先拿一批候选”的场景。

在应用侧封装查询并清理测试数据

命令行确认参数后，再把查询封装到应用侧。下面的 Python 示例使用 redis 客户端的原生命令接口，保留 Redis 返回的字段结构，避免把距离和坐标误当成字符串列表中的固定位置。

import redis

# 连接本地 Redis；生产环境应从配置注入地址和凭据
client = redis.Redis(host="localhost", port=6379, decode_responses=True)

# 以成员作为中心，取 5 千米内最近的 3 个成员并返回距离
rows = client.geosearch(
    "shop:geo",
    member="中心店",
    radius=5,
    unit="km",
    sort="ASC",
    count=3,
    withdist=True,
    withcoord=True,
)

# 统一打印成员、距离和坐标，便于接入 API 的 DTO
for member, distance, coord in rows:
    print({"member": member, "distance_km": distance, "coord": coord})

# 实验结束后删除测试索引，避免下次运行读到旧数据
client.delete("shop:geo")

不同客户端对返回结构的封装名称可能不同，但参数的语义仍对应 Redis 命令：中心点、形状、单位、排序、数量和附加字段。接入前先查看所用客户端的 GEOSEARCH 方法签名，尤其确认 withdist 与 withcoord 是否返回元组、对象或嵌套数组。

常见问题

GEOSEARCH 和 GEORADIUS 该选哪个？

新代码优先使用 GEOSEARCH。Redis 官方文档把 GEORADIUS 标记为自 6.2 起弃用的旧命令，并建议用 GEOSEARCH 配合 BYRADIUS 替代。

为什么查询不到点？

先检查经纬度顺序、单位和中心点是否写反。Redis 约定经度在前、纬度在后；同时确认查询键和写入 GEOADD 使用的是同一个键。

COUNT ANY 能不能用于最近门店？

不建议。需要严格的最近顺序时使用 ASC COUNT n，不要加 ANY；ANY 适合快速拿候选，不承诺结果是最近的 n 个。

总结

GEOSEARCH 的核心是先选边界，再决定返回信息：圆形用 BYRADIUS，矩形用 BYBOX，最近排序用 ASC，距离和坐标分别用 WITHDIST、WITHCOORD。把 COUNT ANY 和精确最近查询区分开，基本就能覆盖附近门店、设备围栏和地图视口这几类常见场景。