h3

pg_h3 : H3 bindings for PostgreSQL

Overview

Packages

Source

pig build pkg pg_h3;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

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

Install this extension with pig:

pig install pg_h3;		# install via package name, for the active PG version
pig install h3;		# install by extension name, for the current active PG version

pig install h3 -v 18;   # install for PG 18
pig install h3 -v 17;   # install for PG 17
pig install h3 -v 16;   # install for PG 16
pig install h3 -v 15;   # install for PG 15
pig install h3 -v 14;   # install for PG 14

Create this extension with:

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.