h3-duckdb

All H3 functions in this extension support the following input and output types:

• UBIGINT (unsigned 64-bit integer)
• BIGINT (signed 64-bit integer)
• VARCHAR (string representation)

Note: The unsigned API is preferred and is the default return type when the extension cannot explicitly detect which type to use. The signed and unsigned APIs are functionally identical.

To use H3 functionality in DuckDB, install the extension from the community repository and then load it into your session.

INSTALL h3 FROM community;
LOAD h3;

After building, you can run the bundled DuckDB shell:

./build/release/duckdb -unsigned

Note: You must run DuckDB with the -unsigned flag to use the H3 extension if you are running a local build. Once inside the shell, load the extension using the path to the .duckdb_extension file:

load 'build/release/extension/h3/h3.duckdb_extension';

The C API headers in the duckdb_capi/ directory should correspond to the TARGET_DUCKDB_VERSION specified in the project's Makefile. To automatically synchronize these headers with the target version, run the following command from the root directory:

make update_duckdb_headers

Manual Updates: You can update headers manually, but ensure they meet these versioning requirements:

1. They must be from the same DuckDB version as TARGET_DUCKDB_VERSION.
2. They must not be from a later release than TARGET_DUCKDB_VERSION.
3. Using headers from an older version is technically allowed but not recommended.

To build the extension from source, you need Git, CMake, and a C compiler. It is recommended to use ninja for faster builds via parallelism.

Build steps

1. Update submodules:

git submodule update --init

2. Build release version:

GEN=ninja make release

Alternatively, using standard make with manual parallelism (replace 4 with your CPU core count):

CMAKE_BUILD_PARALLEL_LEVEL=4 make duckdb_release release

3. Run tests:

make test

4. Update submodules to latest upstream:

make update_deps

The extension provides functions to work with H3 cell IDs. You can use VARCHAR strings, BIGINT (signed), or UBIGINT (unsigned) for H3 indexes. Using the integer API (UBIGINT or BIGINT) generally provides better performance.

Example using a string index:

SELECT h3_cell_to_latlng('822d57fffffffff');

Example using an integer index (preferred for performance):

SELECT h3_cell_to_latlng(586265647244115967);

The WkbEncoder class provides a stateful interface for constructing Well-Known Binary (WKB) representations of geometries. You build the geometry by calling specific lifecycle methods (e.g., StartPolygon, Point) and then retrieve the final binary string using Finish().

Supported geometry types and methods:

• Points: Point(double lng, double lat)
• LineStrings: StartLineString(), EndLineString()
• Polygons: StartPolygon(), EndPolygon()
• MultiPolygons: StartMultiPolygon(uint32_t polygonCount), StartMultiPolygonPolygon(uint32_t loopCount), StartMultiPolygonLoop(), MultiPolygonEmpty(), EndMultiPolygonLoop(), EndMultiPolygonPolygon(), EndMultiPolygon()

h3duckdb::WkbEncoder encoder;
encoder.StartPolygon();
encoder.Point(-122.41, 37.77);
encoder.EndPolygon();
std::string wkb = encoder.Finish();

The WktEncoder class provides a stateful interface for constructing Well-Known Text (WKT) representations of geometries. It manages the necessary delimiters (like commas and parentheses) automatically. Use the lifecycle methods to define the geometry structure and call Finish() to get the resulting string.

Supported geometry types and methods:

• Points: Point(double lng, double lat)
• LineStrings: StartLineString(), EndLineString()
• Polygons: StartPolygon(), EndPolygon()
• MultiPolygons: StartMultiPolygon(uint32_t polygonCount), StartMultiPolygonPolygon(uint32_t loopCount), StartMultiPolygonLoop(), MultiPolygonEmpty(), EndMultiPolygonLoop(), EndMultiPolygonPolygon(), EndMultiPolygon()

h3duckdb::WktEncoder encoder;
encoder.StartPolygon();
encoder.Point(-122.41, 37.77);
encoder.EndPolygon();
std::string wkt = encoder.Finish();