Redis GEO：没有地图，怎么查附近——Redis系列(十二)

# 一、Redis Geo类型是什么？
-  Redis GEO 是 Redis 3.2 版本引入的地理位置（Geospatial）功能，用于存储、计算和查询经纬度坐标。
-  Redis GEO 是一种面向LBS（Location-Based Service）应用的数据类型
- 它并不是一种全新的底层数据结构，而是基于有序集合（Sorted Set / ZSet）实现的一层封装——坐标被编码成一个 52 位整数（GeoHash）作为 score，成员名作为 value。
- Redis GEO 用 Haversine 公式（假设地球是半径固定的球）在球面地球模型上算距离 —— 近似值，最坏误差 0.5%（约 5 公里 / 1000 公里量级），适合社交网络、推荐附近商家等精度要求不高的LBS场景，不适合高精度关键系统（航海、航空、测绘、自动驾驶）

# 二、 Geohash科普
# 2.1 什么是Geohash
**Geohash** 是一种**将二维经纬度（经度、纬度）坐标编码成一维字符串**的地理编码算法。核心思想：把地球经纬度空间不断二分（递归划分网格），给每个网格分配一个唯一字符串，同一个网格内所有点拥有相同 Geohash。**相近地理位置，通常拥有相似前缀**。Redis 的 GEO 底层就是基于 Geohash 实现。
## 2.2 Geohash 编码方法
### 步骤 1：确定经纬度范围
- 纬度范围：`[-90, 90]` （注意Redis的维度范围是`[-85, 85]` )
- 经度范围：`[-180, 180]`
基础编码表（base32，32 个字符）：
`0123456789bcdefghjkmnpqrstuvwxyz`
注意：去掉了容易混淆的 `a,i,l,o`
### 步骤 2：分别对经度、纬度做**二分迭代**，生成二进制串
对经度区间不断二分：
经度范围[-180,180]会被分成两个子区间：[-180,0) 和[0,180]（我称之为左、右分区）
- 坐标落在**右半区间 → 记 1**
- 坐标落在**左半区间 → 记 0**
经度同理，单独生成一串二进制。
举一个例子 （经度116.37维度39.86），经度编码：
![](https://developer.qcloudimg.com/http-save/yehe-9980940/01766076e8888590786a9362752c7174.webp)
维度编码：
![image](https://developer.qcloudimg.com/http-save/yehe-9980940/5ce5bfe3443cfd2bf7b47735b30f0203.webp)

我们刚刚计算的经纬度（116.37，39.86）的各自编码值是 11010 和 10111，组合之后，第 0 位是经度的第 0 位 1，第 1 位是纬度的第 0 位 1，第 2 位是经度的第 1 位 1，第 3 位是纬度的第 1 位 0，以此类推，就能得到最终编码值 1110011101，如下图所示：
![image](https://developer.qcloudimg.com/http-save/yehe-9980940/a07ff0036cd9977594defc0272a46868.webp)

将11100 11101 转成十进制，对应着28、29十进制对应的base32编码就是wx

**扩展阅读**
[Geohash原理](https://cloud.tencent.com/developer/article/2219830)
[地理空间编码算法之GeoHash](https://zhuanlan.zhihu.com/p/386445188)

# 三、Redis Geo类型常用命令
| 命令               | 作用                                           | 示例                                                            |
| ---------------- | -------------------------------------------- | ------------------------------------------------------------- |
| `GEOADD`         | 添加坐标（member → 经纬度）                           | GEOADD site 116.404269 39.913164 天安门                          |
| `GEOPOS`         | 查询某成员坐标                                      | `GEOPOS site 天安门`                                             |
| `GEODIST`        | 计算两点距离                                       | `GEODIST geo:shops A B km`                                    |
| `GEOSEARCH`      | **按半径 / 矩形查找附近成员**（Redis 6.2 起，替代 GEORADIUS） | `GEOSEARCH geo:shops FROMLONLAT 116.4 39.9 BYRADIUS 5 km ASC` |
| `GEOSEARCHSTORE` | 查询结果存到新 key                                  | 常用于缓存热门区域结果                                                   |
| `GEOHASH`        | 返回成员的标准 GeoHash 字符串                          | `GEOHASH geo:shops A`                                         |
| `GEORADIUS`      |                                              |                                                               |

## 1. GEOADD
添加坐标
可以使用 [百度地图提供的经纬度查询工具](http://api.map.baidu.com/lbsapi/getpoint/index.html)查找坐标
**语法：**
```bash
GEOADD key [NX | XX] [CH] longitude latitude member [longitude
  latitude member ...]
```
- `longitude` 表示经度，有效经度 -180 到180 度
- `latitude` 表示纬度，有效纬度latitudes  -85.05112878 到 85.05112878度
- `member` 是为此经纬度起的名字
当用户尝试为指定范围之外的坐标编制索引时，该命令将报告错误。
---
`GEOADD`还提供以下选项：
- **XX：**仅更新已存在的元素。从不添加元素。
- **NX：**不要更新已存在的元素。始终添加新元素。
- **CH：**将返回值从添加的新元素数修改为已更改元素的总数（CH 是 _changed_ 的缩写）。更改的元素是**添加的新元素**和已**存在的元素，这些元素的坐标已更新**。因此，在命令行中指定的元素与过去具有相同的分数不会被计算在内。注意：正常情况下，`GEOADD`仅计算添加的新元素的数量。

注： **XX** 和 **NX** 选项是互斥的。

## 2. GEOPOS
查询某成员坐标
**语法：**
```txt
GEOPOS key [member [member ...]]
```
返回排序集合（sorted set）所表示的**地理空间索引**中，所有指定成员的位置（经度，纬度）。

对于一个用 `GEOADD` 命令填充的地理空间索引，常常需要取回指定成员的坐标。当通过 `GEOADD` 填充地理空间索引时，坐标会被转换成 **52 位 geohash**，因此返回的坐标可能与添加元素时使用的坐标**不完全一致**，可能会引入微小误差

```bash
127.0.0.1:6379> geoadd site 116.404269 39.913164 天安门
(integer) 0
127.0.0.1:6379> geoadd site 116.36 39.922461 月坛
(integer) 0

127.0.0.1:6379> GEOPOS site 天安
1) (nil)
   
127.0.0.1:6379> GEOPOS site 天安门
1) 1) "116.40426903963088989"
   2) "39.91316289865136469"
```

## 3. GEODIST
返回排序集合（sorted set）所表示的**地理空间索引**中，两个成员之间的距离
如果其中一个或两个成员不存在，命令返回 **NULL**
距离的计算**假设地球是一个完美的球体**，因此在边界情况下可能存在最高 **0.5%** 的误差

**语法：**
```
GEODIST key member1 member2 [M | KM | FT | MI]
```

距离单位必须是以下之一，**默认是米（m）**：
- `m` —— 米（meters）
- `km` —— 千米（kilometers）
- `mi` —— 英里（miles）
- `ft` —— 英尺（feet）
```bash
127.0.0.1:6379> geodist site  天安门 月坛
"3915.3220"
127.0.0.1:6379> geodist site  天安门 月坛 km
"3.9153"
127.0.0.1:6379> geodist site  天安门 月坛 mi
"2.4329"
127.0.0.1:6379> geodist site  天安门 月坛 ft
"12845.5445"
```

## 4. GEOSEARCH
返回通过 `GEOADD` 录入地理信息的有序集合中，落在指定图形区域范围内的成员。该命令是 `GEORADIUS` 命令的扩展，除了圆形区域检索外，还支持矩形区域检索。
Redis6.2.0 版本引入，本命令应当用来替代已经废弃的 `GEORADIUS` 和 `GEORADIUSBYMEMBER` 命令。
https://redis.io/docs/latest/commands/geosearch/
**语法：**
```
GEOSEARCH key <FROMMEMBER member | FROMLONLAT longitude latitude>
  <BYRADIUS radius <M | KM | FT | MI> | BYBOX width height <M | KM |
  FT | MI>> [ASC | DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST]
  [WITHHASH]
```
- `key` 存储地理空间索引（有序集合）的键名

- `中心二选一`
  - `FROMMEMBER member` 以集合内已有成员的坐标作为搜索中心点。和 `FROMLONLAT` 互斥
  - `FROMLONLAT longitude latitude` 使用给定经纬度作为搜索中心点。和 `FROMMEMBER` 互斥
- `查询图形选项（二者互斥）`
  - `BYRADIUS radius M | KM | FT | MI`在指定单位、给定半径的圆形范围内搜索。和 `BYBOX` 互斥
  - `BYBOX width height M | KM | FT | MI`在给定宽、高的**轴对齐矩形**内搜索，单位可选。和 `BYRADIUS` 互斥
可选参数：

| 参数 | 作用 |
| --- | --- |
| `WITHDIST` | 额外返回成员距离中心点的距离，单位和半径指定单位保持一致 |
| `WITHCOORD` |  额外返回每个匹配成员的经纬度坐标 |
| `WITHHASH` | 额外返回原始的 52 位 geohash 编码整数值（zset 的 score） |
| `ASC` / `DESC` | 按距离中心点排序结果：`ASC` 由近到远；`DESC` 由远到近 |
| `COUNT n` | 最多返回 n 个，注意：不加 ANY 时，Redis 需要检索区域内全部匹配数据并排序。如果查询超大范围、COUNT 很小，即便只返回少量结果，查询也可能很慢 |
| `COUNT n ANY` | 凑够 n 个就停，更快，但**结果不一定有序**|

```bash
127.0.0.1:6379> geosearch site frommember tianan bybox 5 5 km
1) "tianan"
2) "forbiddencity"
```

## 5. GEOHASH
语法：
```
GEOHASH key [member [member ...]]
```
返回一个或多个元素的**有效 Geohash 字符串**，这些元素存在于表示地理空间索引的排序集合（sorted set）中（元素通过 `GEOADD` 命令添加）
通常，Redis 使用 Geohash 技术的一个**变体**来表示元素位置，其位置用 **52 位整数**编码。这种编码与标准 Geohash 也不同，因为其编码和解码过程中使用的**初始最小 / 最大坐标范围不同**。该命令返回的是标准 Geohash—— 即 [维基百科 Geohash](https://en.wikipedia.org/wiki/Geohash) 所描述的那种**字符串形式**

```bash
127.0.0.1:6379> geohash site tianan yuetan
1) "wx4g0cgp000"
2) "wx4epgdv0t0"
```
## 6. GEO删除
没有 GEODEL，删除直接用 `ZREM`（本质数据结构底层就是 **ZSet**）

# 四、 GEO 的底层结构
Redis GEO**不是独立的数据类型**，底层就是 **ZSet（有序集合）**，ZSet 底层是**跳表 + 哈希表**Redis。详细见[Redis的SortedSet类型数据结构——Redis系列(七)](https://cloud.tencent.com/developer/article/2701710)

GEO 本质：**把经纬度编码成 52 位 GeoHash 整数，放到 ZSet 的 score 字段**，member 是地点名称。
## 4.1 一个点在内存中长什么样
 `GEOADD`：经纬度 → 52 位 GeoHash 整数 → ZADD 写入 zset
例如
```
key: 自定义geo索引key（如:shop:geo） 
ZSet: 
member: 门店id/名称（字符串，唯一） 
score: 52bit GeoHash编码整数（double存储，刚好无损保存52bit整数）
```


## 4.2 附近搜索实际跑了什么

1. **估精度。** 按搜索半径（矩形则按外接圆）和纬度，选一个 Geohash 步长。半径越大，格子越大，步长越小。
2. **切九宫格。** 根据搜索半径，自动选择 Geohash 网格精度 + 生成九宫格/圆心所在格子，加上东、西、南、北、东北、西北、东南、西南，最多 9 块。有的邻居在极地、日期变更线外会被丢掉；有的会和中心格子编号撞车，去重。
3. **格子 → score 区间。** ZSet 跳表区间查询，粗筛候选点。每个格子对应一段连续的 52 位前缀，对齐成 `[min, max)`，利用 ZSet 底层跳表，`O(logM)`定位区间起点，取出网格内全部 member+score。
4.  **Haversine（或矩形）过滤。** 格子是方的，圆/框是查询形状，格子里会有漏网之鱼。
    - 将 score（52 位 Geohash 整数）反向解码还原成原始经纬度
    - **哈弗辛公式 Haversine**，计算该点与中心点的球面大圆距离
    - 保留距离 ≤ 搜索半径的点，剔除落在矩形但圆外的点
5. **排序、截断。** `ASC`/`DESC`、`COUNT` 在这一步做。`COUNT ANY` 可以在凑够数量后提前停，少扫几块格子

Redis GEO 是 Redis 3.2 版本引入的地理位置（Geospatial）功能，用于存储、计算和查询经纬度坐标。

Redis GEO：没有地图，怎么查附近——Redis系列(十二)

后端

RedisGEO是Redis 3.2引入的地理位置功能，基于有序集合和Geohash编码实现经纬度存储与计算。支持GEOADD添加坐标、GEOSEARCH按半径或矩形搜索附近成员、GEODIST计算球面距离等命令，底层通过52位GeoHash整数作为score实现高效查询，适用于LBS场景如附近商家推荐。

自动驾驶

数据结构

代码解释

Redis

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Redis GEO：没有地图，怎么查附近——Redis系列(十二)-腾讯云开发者社区-腾讯云

Redis GEO：没有地图，怎么查附近——Redis系列(十二)

Redis GEO：没有地图，怎么查附近——Redis系列(十二)

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐