h3

Overview

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.

Version

Build

You can build the RPM / DEB packages for pg_h3 using pig build:

pig build pkg pg_h3         # build RPM / DEB packages

Install

You can install pg_h3 directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

pig install pg_h3;          # Install for current active PG version

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:

CREATE EXTENSION h3;

Usage

Sources:

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

h3 exposes the H3 hierarchical hexagonal grid through PostgreSQL. Its h3index type stores cell, directed-edge, and vertex identifiers. Use it to assign coordinates to cells, aggregate by resolution, and traverse neighborhoods. The extension does not require preloading.

Upgrade to 4.5.0

Install matching files before updating each database. The update automatically rebuilds affected H3 btree indexes because earlier comparators physically sorted them in the wrong order. The migration can also recompute stored distance-dependent generated columns, rebuild dependent indexes, and refresh dependent materialized views. Plan for locks, writes, and maintenance time; a library replacement alone does not perform these operations.

ALTER EXTENSION h3 UPDATE TO '4.5.0';

For manually scheduled btree rebuilds, upstream recommends dropping affected indexes before the extension update and recreating them afterward. Install the 4.5.0 package files before requesting this extension update.

Index a Location

PostgreSQL points use longitude, latitude in degrees. Do not pass projected coordinates or swap the axes. Resolution ranges from 0 to 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 defaults to false; enabling it rejects out-of-range coordinates. h3.extend_antimeridian controls boundary handling at the 180-degree meridian; leave it false for typical planar PostGIS operations.

Core API

Version 4.5.0 adds the general identifier validator, explicit cell-component helpers, and edge reversal. Prefer the new ring API to the unsafe variant near pentagons; neighborhood row order is not guaranteed. Grid-distance and path operations can fail for distant cells or pentagonal distortion.

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

Operators and Indexes

Equality and ordering support btree indexes; containment and overlap use @>, <@, and &&. The <-> operator returns grid distance, with a maximum-bigint sentinel where distance calculation fails. It is not a physical distance in meters.

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 and SP-GiST operator classes are experimental. For geometry, geography, raster, and SRID-aware workflows, use the separate h3_postgis extension. Validate polygons before converting them to cells; invalid polygons can produce undefined results or unexpectedly large output.