h3_postgis

概览

RPM and DEB 4.5.0 require h3, postgis and postgis_raster; point coordinates use longitude, latitude.

版本

构建

您可以使用 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_postgis CASCADE;  -- 依赖: h3, postgis, postgis_raster

用法

来源：

• 4.5.0 PostGIS API
• Dependencies and extension definition
• 4.5.0 migration SQL
• 4.5.0 release

h3_postgis 将 H3 单元格与 PostGIS 几何、地理及栅格数据连接起来。它依赖 h3、postgis 和 postgis_raster，即便仅处理几何也需要这些依赖。输入几何必须使用 SRID 4326，坐标顺序为经度、纬度；这些函数不会自动重新投影输入。

点与单元格转换

CREATE EXTENSION h3_postgis CASCADE;
SET h3.strict = true;

SELECT h3_latlng_to_cell(
    ST_SetSRID(ST_MakePoint(-122.0553238, 37.3615593), 4326), 9
);
SELECT h3_cell_to_geometry('85283473fffffff'::h3index);
SELECT h3_cell_to_boundary_geometry('85283473fffffff'::h3index);

其他坐标系应先通过 PostGIS 转换到 SRID 4326，再调用 H3 函数。仅设置 SRID 标签不会转换坐标。

核心接口

几何与分辨率之间的 @ 运算符也能将位置映射到 H3 单元格。使用 ST_IsValid() 检查多边形；ST_MakeValid() 修复可能改变拓扑并产生几何集合，应在覆盖计算前提取并检查多边形部分。无效多边形的行为未定义。

汇总栅格数据

SELECT (summary).h3,
       (h3_raster_summary_stats_agg((summary).stats)).*
FROM (
    SELECT h3_raster_summary(rast, 8) AS summary
    FROM rasters
) AS r
GROUP BY (summary).h3;

默认汇总函数会自动选择方法，也可显式使用裁剪、像素中心或子像素变体控制像素如何分配到单元格。应结合栅格分辨率和目标 H3 分辨率检查所选方法。

升级与边界

ALTER EXTENSION h3 UPDATE TO '4.5.0';
ALTER EXTENSION h3_postgis UPDATE TO '4.5.0';

基础扩展更新会重建受影响的 btree 索引并刷新距离依赖对象，应先安排维护窗口，再更新伴随扩展。4.5.0 修复 PostgreSQL 17+ 受限搜索路径下的维护、表达式索引导出恢复，以及多项几何和多边形生成错误。两个扩展版本应保持一致。更新任一扩展前，先安装匹配的 4.5.0 软件包文件。

平面叠加运算通常应保持 h3.extend_antimeridian 为 false。两个扩展都可重定位；执行未限定模式的 SQL 时，应确保 H3 和 PostGIS 所在模式可见。两者均无需共享预加载。