Redis GEOSEARCHSTORE 怎样把附近地点查询保存为有序集合

如果你已经用 Redis 保存了一组带经纬度的地点，想把“某个中心点附近的结果”直接留下来供后续排序、分页或二次处理，GEOSEARCHSTORE 就是对应的命令。它从源地理索引读取结果，把结果写入指定的 destination 有序集合；原查询 key 不会被当成结果集覆盖。

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

最小可用写法是：先用 GEOADD places:geo 建立地点索引，再执行 GEOSEARCHSTORE places:nearby places:geo FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 20。如果后续要让有序集合的 score 直接代表距离，就在末尾加 STOREDIST。

一、先把 source 和 destination 的职责分开

GEOSEARCHSTORE 的前两个参数分别是目标 key 和源 key。源 key 必须是地理索引，目标 key 用来保存本次查询得到的成员。先把两者命名区分开，后续排查“查不到”或“结果被覆盖”会简单很多。

# 写入三个地点；经度在前，纬度在后
redis-cli GEOADD places:geo 121.4737 31.2304 "人民广场" \
  121.4903 31.2397 "外滩" \
  121.4444 31.2222 "静安寺"

# 在中心点 5 千米内查找，结果写入新的有序集合
redis-cli GEOSEARCHSTORE places:nearby places:geo \
  FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 20

# 返回值是本次写入目标集合的成员数量
redis-cli ZCARD places:nearby

这组命令里的 places:geo 是查询来源，places:nearby 是查询结果。GEOSEARCHSTORE 是写命令：同名 destination 已存在时，结果会写入这个目标集合，因此目标 key 最好使用“查询条件或版本”可识别的命名，避免把不同业务结果误认为同一份快照。

二、用中心点和范围参数表达附近查询

中心点有两种写法：FROMMEMBER member 复用源索引里已有成员的位置，FROMLONLAT longitude latitude 直接给经纬度。二者互斥，不能同时出现。

范围也有两种写法：BYRADIUS radius unit 表示圆形范围，BYBOX width height unit 表示轴对齐矩形范围。单位可用 M、KM、FT 或 MI，同一条命令只能选择一种范围形状。

# 以已有地点“人民广场”为中心，查询 3 千米圆形范围
redis-cli GEOSEARCHSTORE places:from-member places:geo \
  FROMMEMBER "人民广场" BYRADIUS 3 KM ASC

# 以经纬度为中心，查询宽 8 千米、高 4 千米的轴对齐矩形
redis-cli GEOSEARCHSTORE places:box places:geo \
  FROMLONLAT 121.4737 31.2304 BYBOX 8 4 KM ASC

如果用 FROMMEMBER，成员必须已经存在于 source 地理索引；如果用 FROMLONLAT，则应确认经度、纬度顺序没有写反。圆形适合“半径内附近”，矩形适合地图视口或运营区域这类横纵范围更明确的查询。

三、用 ASC、DESC、COUNT 和 ANY 控制结果集合

ASC 按距离从近到远排列，DESC 则从远到近。COUNT count 将结果数量限制在指定上限内；没有 COUNT 时，命令会把符合范围的成员全部写入 destination。

COUNT count ANY 适合只关心“尽快拿到足够多结果”的场景。官方说明中，ANY 找到足够数量后即可返回，速度可能更快，但返回结果不保证有序；如果页面需要严格的最近优先，就不要把 ANY 和“有序”同时当成强约束。

# 最近的 10 个地点，保持距离顺序
redis-cli GEOSEARCHSTORE places:nearest10 places:geo \
  FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 10

# 只要尽快找到最多 10 个候选，不把返回顺序当作最近优先
redis-cli GEOSEARCHSTORE places:fast10 places:geo \
  FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 10 ANY

目标集合保存的是本次命中的成员，不是一个自动更新的“附近地点视图”。源索引后续变化后，旧 destination 不会自动重算；需要刷新时应重新执行命令，并让调用方把目标 key 当作一次结果快照来管理。

四、用 STOREDIST 决定 score 的业务含义

这是 GEOSEARCHSTORE 最容易被忽略的区别。默认情况下，目标 sorted set 的 score 保存的是地理编码位置；加上 STOREDIST 后，score 改为中心点到成员的距离，且单位与 BYRADIUS 或 BYBOX 使用的单位一致。

# 默认模式：目标集合保存地理编码位置，不要把 score 直接当米数
redis-cli GEOSEARCHSTORE places:geo-score places:geo \
  FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 20

# 距离模式：score 直接表示以 KM 为单位的距离
redis-cli GEOSEARCHSTORE places:distance places:geo \
  FROMLONLAT 121.4737 31.2304 BYRADIUS 5 KM ASC COUNT 20 STOREDIST

# 读取距离模式的成员和 score；这里的 score 才能按千米解释
redis-cli ZRANGE places:distance 0 -1 WITHSCORES

如果业务要展示“距离 1.24 千米”、按距离区间再次筛选，或将 score 交给其他 sorted-set 操作，STOREDIST 通常更直接。相反，如果后续还需要保留 Redis 地理集合的编码语义，就不要因为看到 score 是浮点数而误判为距离。

五、迁移和生产使用时要记住的边界

GEOSEARCHSTORE 自 Redis 6.2.0 提供，官方文档将它列为已弃用 GEORADIUS 和 GEORADIUSBYMEMBER 的替代方向。迁移旧代码时，重点不是机械替换命令名，而是重新确认“结果是否要保存”“score 是否要表示距离”这两个业务语义。

官方给出的复杂度是 O(N+log(M))，其中 N 与过滤形状覆盖的网格区域元素有关，M 与形状内的项目数有关。大范围查询、过大的 COUNT 或频繁刷新 destination 都可能让写入压力上升，应结合实际数据分布观察，而不是只看命令名称判断性能。

在 Redis Cluster 中，这条命令同时访问 source 和 destination 两个 key。多 key 命令会受到集群路由约束，生产命名时应按部署方式确认两个 key 能在同一 slot 工作；若 key 已经是其他数据类型，还应把 WRONGTYPE 与“没有匹配结果”分开处理。

总结

Redis GEOSEARCHSTORE 的核心是“查询并保存”：source 是地理索引，destination 是结果有序集合；FROMMEMBER 与 FROMLONLAT 选择中心，BYRADIUS 与 BYBOX 选择范围；ASC、DESC、COUNT、ANY 控制结果；STOREDIST 决定 score 是否直接表示距离。迁移或新建功能时，先把这几个语义写进接口契约，再决定目标 key 的刷新策略。

常见问题

GEOSEARCHSTORE 会修改源地理索引吗？

它查询 source 并把结果写入 destination，源索引不是结果写入目标。需要注意的是 destination 会承接本次结果，因此不要把它误当成自动随 source 更新的视图。

为什么 ZRANGE 读到的 score 不能直接当距离？

默认模式保存的是地理编码位置。只有显式使用 STOREDIST，score 才是以所选 M、KM、FT 或 MI 为单位的距离。

COUNT 后面一定要加 ANY 吗？

不需要。COUNT 只限制数量；ANY 是可选的提前返回策略，适合优先速度而不要求结果严格有序的场景。

BYRADIUS 和 BYBOX 怎么选？

按半径搜索附近地点用 BYRADIUS；按地图视口或规则区域筛选用 BYBOX。两者在一条命令里互斥。