This is a DuckDB extension that adds support for the H3 discrete global grid system.

Download

Download the latest version of the extension: Linux AMD64 Linux AMD64 GCC4 Linux Arm64 OSX AMD64 OSX Arm64 wasm eh wasm mvp wasm threads Windows AMD64

For Linux x64:

wget https://pub-cc26a6fd5d8240078bd0c2e0623393a5.r2.dev/v0.10.3/linux_amd64_gcc4/h3ext.duckdb_extension.gz
gunzip h3ext.duckdb_extension.gz

Install

Run DuckDB with the unsigned option:

duckdb -unsigned

Note: you must download and ungzip the extension to install it.

Load the extension:

install 'h3ext.duckdb_extension';
load 'h3ext';

Test running an H3 function:

SELECT h3_cell_to_latlng('822d57fffffffff');

Or, using the integer API, which generally has better performance:

SELECT h3_cell_to_latlng(cast(586265647244115967 as ubigint));

Implemented functions

This extension implements the entire H3 API. The full list of functions is below.

All functions support H3 indexes specified as UBIGINT (uint64) or BIGINT (int64), but the unsigned one is preferred and is returned when the extension can't detect which one to use. The unsigned and signed APIs are identical. Many functions also support VARCHAR H3 index input and output.

Full list of functions

Function	Notes	Description
h3_latlng_to_cell	u	Convert latitude/longitude coordinate to cell ID
h3_cell_to_lat	v	Convert cell ID to latitude
h3_cell_to_lng	v	Convert cell ID to longitude
h3_cell_to_latlng	v	Convert cell ID to latitude/longitude
h3_cell_to_boundary_wkt	v	Convert cell ID to cell boundary
h3_get_resolution	i	Get resolution number of cell ID
h3_get_base_cell_number	i	Get base cell number of cell ID
h3_string_to_h3	u	Convert VARCHAR cell ID to UBIGINT
h3_h3_to_string	i	Convert BIGINT or UBIGINT cell ID to VARCHAR
h3_is_valid_cell	v	True if this is a valid cell ID
h3_is_res_class_iii	i	True if the cell's resolution is class III
h3_is_pentagon	i	True if the cell is a pentagon
h3_get_icosahedron_faces	i	List of icosahedron face IDs the cell is on
h3_cell_to_parent	i	Get coarser cell for a cell
h3_cell_to_children	i	Get finer cells for a cell
h3_cell_to_center_child	i	Get the center finer cell for a cell
h3_cell_to_child_pos	i	Get a sub-indexing number for a cell inside a parent
h3_child_pos_to_cell	i	Convert parent and sub-indexing number to a cell ID
h3_compact_cells	i	Convert a set of single-resolution cells to the minimal mixed-resolution set
h3_uncompact_cells	i	Convert a mixed-resolution set to a single-resolution set of cells
h3_grid_disk	i	Find cells within a grid distance
h3_grid_disk_distances	i	Find cells within a grid distance, sorted by distance
h3_grid_disk_unsafe	i	Find cells within a grid distance, with no pentagon distortion
h3_grid_disk_distances_unsafe	i	Find cells within a grid distance, sorted by distance, with no pentagon distortion
h3_grid_ring_unsafe	i	Find cells exactly a grid distance away, with no pentagon distortion
h3_grid_path_cells	i	Find a grid path to connect two cells
h3_grid_distance	i	Find the grid distance between two cells
h3_cell_to_local_ij	i	Convert a cell ID to a local I,J coordinate space
h3_local_ij_to_cell	i	Convert a local I,J coordinate to a cell ID
h3_cell_to_vertex	i	Get the vertex ID for a cell ID and vertex number
h3_cell_to_vertexes	i	Get all vertex IDs for a cell ID
h3_vertex_to_lat	i	Convert a vertex ID to latitude
h3_vertex_to_lng	i	Convert a vertex ID to longitude
h3_vertex_to_latlng	i	Convert a vertex ID to latitude/longitude coordinate
h3_is_valid_vertex	v	True if passed a valid vertex ID
h3_is_valid_directed_edge	v	True if passed a valid directed edge ID
h3_origin_to_directed_edges	i	Get all directed edge IDs for a cell ID
h3_directed_edge_to_cells	i	Convert a directed edge ID to origin/destination cell IDs
h3_get_directed_edge_origin	i	Convert a directed edge ID to origin cell ID
h3_get_directed_edge_destination	i	Convert a directed edge ID to destination cell ID
h3_cells_to_directed_edge	i	Convert an origin/destination pair to directed edge ID
h3_are_neighbor_cells	i	True if the two cell IDs are directly adjacent
h3_directed_edge_to_boundary_wkt	v	Convert directed edge ID to linestring WKT
h3_get_hexagon_area_avg		Get average area of a hexagon cell at resolution
h3_cell_area	v	Get the area of a cell ID
h3_edge_length	v	Get the length of a directed edge ID
h3_get_num_cells		Get the number of cells at a resolution
h3_get_res0_cells	u	Get all resolution 0 cells
h3_get_pentagons	u	Get all pentagons at a resolution
h3_great_circle_distance		Compute the great circle distance between two points (haversine)
h3_cells_to_multi_polygon_wkt	v	Convert a set of cells to multipolygon WKT
h3_polygon_wkt_to_cells	u	Convert polygon WKT to a set of cells

Notes

• v: Supports VARCHAR, UBIGINT, and BIGINT input and output.
• i: Supports UBIGINT and BIGINT input and output. (TODO for these to support VARCHAR too.)
• u: Supports UBIGINT output only.

Development

To build, type:

git submodule update --init
GEN=ninja make release

You will need Git, CMake, and a C compiler. The build instructions suggest using ninja because it enables parallelism by default. Using make instead is fine, but you will want to enable the following parallelism option, because building DuckDB can take a very long time (>=1 hour is not unusual). Run the below replacing 4 with the number of CPU cores on your machine.

CMAKE_BUILD_PARALLEL_LEVEL=4 make duckdb_release release

To run, run the bundled duckdb shell:

./build/release/duckdb -unsigned

Load the extension:

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

To run tests:

make test

To update the submodules to latest upstream, run:

make update_deps

License

h3-duckdb Copyright 2022 Isaac Brodsky. Licensed under the Apache 2.0 License.

H3 Copyright 2018 Uber Technologies Inc. (Apache 2.0 License)

DGGRID Copyright (c) 2015 Southern Oregon University

DuckDB Copyright 2018-2022 Stichting DuckDB Foundation (MIT License)

DuckDB extension-template Copyright 2018-2022 DuckDB Labs BV (MIT License)