h3

概览

RPM and DEB 4.5.0 statically link the pinned H3 core; point coordinates use longitude, latitude. Reindex affected h3index btree and distance-dependent indexes after upgrading.

版本

构建

您可以使用 pig build 命令构建 pg_h3 扩展的 RPM / DEB 包：

pig build pkg pg_h3         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_h3 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install pg_h3;          # 当前活跃 PG 版本安装

pig ext install -y pg_h3 -v 18  # PG 18
pig ext install -y pg_h3 -v 17  # PG 17
pig ext install -y pg_h3 -v 16  # PG 16
pig ext install -y pg_h3 -v 15  # PG 15
pig ext install -y pg_h3 -v 14  # PG 14

dnf install -y h3-pg_18       # PG 18
dnf install -y h3-pg_17       # PG 17
dnf install -y h3-pg_16       # PG 16
dnf install -y h3-pg_15       # PG 15
dnf install -y h3-pg_14       # PG 14

apt install -y postgresql-18-h3   # PG 18
apt install -y postgresql-17-h3   # PG 17
apt install -y postgresql-16-h3   # PG 16
apt install -y postgresql-15-h3   # PG 15
apt install -y postgresql-14-h3   # PG 14

创建扩展：

CREATE EXTENSION h3;

用法

来源：

• h3-pg 4.5.0 API
• Extension definition
• Coordinate bindings
• 4.5.0 migration SQL
• 4.5.0 release

h3 在 PostgreSQL 中提供 H3 分层六边形网格。h3index 类型保存单元格、有向边和顶点标识符，可用于将坐标映射到网格、按分辨率聚合及遍历邻域。扩展无需预加载。

升级到 4.5.0

安装匹配的文件后，在每个数据库中更新扩展。更新会自动重建受影响的 H3 btree 索引，因为旧比较器导致索引中的物理排序方向错误。迁移还可能重新计算依赖距离运算的存储生成列、重建相关索引并刷新相关物化视图。应为锁、写入和维护时间预留窗口；仅替换库文件不会执行这些操作。

ALTER EXTENSION h3 UPDATE TO '4.5.0';

若需手动安排 btree 重建，上游建议在扩展更新前删除受影响的索引，更新后重新创建。请求上述扩展更新前，先安装 4.5.0 软件包文件。

将坐标映射到单元格

PostgreSQL 点坐标顺序为 经度、纬度，单位为度。不要传入投影坐标或交换坐标轴。分辨率范围是 0 到 15。

CREATE EXTENSION h3;
SET h3.strict = true;

SELECT h3_latlng_to_cell(POINT(-122.0553238, 37.3615593), 5);
SELECT h3_cell_to_latlng('85283473fffffff'::h3index);
SELECT h3_cell_to_boundary('85283473fffffff'::h3index);

h3.strict 默认为 false，开启后拒绝越界坐标。h3.extend_antimeridian 控制 180 度经线附近的边界处理，常见的 PostGIS 平面运算应保持 false。

核心接口

4.5.0 新增通用标识符校验、显式单元格分量构造及有向边反转。五边形附近应优先使用新的环遍历接口，避免不安全变体；邻域返回行不保证顺序。距离和路径计算可能因单元格相距过远或五边形畸变失败。

SELECT h3_grid_disk('85283473fffffff'::h3index, 2);
SELECT h3_grid_ring('85283473fffffff'::h3index, 1);
SELECT h3_cell_to_parent('85283473fffffff'::h3index, 3);

运算符与索引

等值和排序支持 btree 索引，包含与相交运算使用 @>、<@ 和 &&。<-> 返回网格距离，无法计算时返回 bigint 最大值作为哨兵值；它不是以米计量的物理距离。

CREATE TABLE locations (cell h3index);
CREATE INDEX locations_cell_btree ON locations (cell);
CREATE INDEX locations_cell_gist ON locations
USING gist (cell h3index_gist_ops_experimental);

GiST 和 SP-GiST 运算符类仍为实验功能。涉及几何、地理、栅格及 SRID 的工作流，应使用独立的 h3_postgis 扩展。将多边形转换为单元格前先检查有效性，无效多边形可能产生未定义结果或异常庞大的输出。