DuckDB DGGS Function Reference

June 15, 2026 · View on GitHub

duck_dggs

A DuckDB extension for discrete global grid systems (DGGS) powered by DGGRID v8.
Transforms geographic coordinates to and from DGGS cell identifiers across multiple coordinate reference frames.

Documentation

Quick start

This extension exposes DGGRID Discrete Global Grid System (DGGS) operations as DuckDB scalar functions. To learn more about DGGRID with interactive demos visit WebDggrid documents.

INSTALL duck_dggs FROM community;
LOAD duck_dggs;

-- Geographic point → cell ID at resolution 5 (default ISEA4H grid)
SELECT geo_to_seqnum('POINT(0.0 0.0)'::GEOMETRY, 5);
-- → 2380

-- Cell ID → cell centre point
SELECT seqnum_to_geo(2380, 5);
-- → POINT (-0.9020481125846749 -1.2067949803565235e-09)

-- Cell ID → cell boundary polygon (requires the spatial extension)
LOAD spatial;
SELECT seqnum_to_boundary(2380, 5);
-- → POLYGON ((0.095 0.667, -0.922 1.336, -1.916 0.669, -1.916 -0.669, -0.922 -1.336, 0.095 -0.667, 0.095 0.667))

-- Use a custom grid (ISEA3H — aperture 3 hexagons)
SELECT geo_to_seqnum('POINT(0.0 0.0)'::GEOMETRY, 5,
    dggs_params('ISEA', 3, 'HEXAGON', 0.0, 58.28252559, 11.25));
-- → 572

Development

See docs/DEVELOPMENT.md for build and test instructions.

Native tests run with make test. To verify the deployed WASM build loads and runs the test suite in WebAssembly:

make test_wasm         # published tests against the live WASM artifact
make test_wasm_local   # this working tree's tests against the live artifact

Both wrap scripts/test-wasm.sh (clones the WASM tester into build/wasm-test/ and auto-detects the deployed catalog version; needs Node 18+). See docs/DEVELOPMENT.md for details.

DuckDB DGGS Function Reference

All transform functions convert between coordinate representations of DGGS cells at a given resolution. Every function has a second overload that accepts an explicit dggs_params struct for full control over the grid configuration.

Coordinate Systems

Symbol	Type	Description
GEO	`GEOMETRY` (POINT)	Geographic lon/lat as a WKB point. `x` = longitude°, `y` = latitude°.
SEQNUM	`UBIGINT`	Global sequential cell index.
Q2DI	`STRUCT(quad UBIGINT, i BIGINT, j BIGINT)`	Quad number + integer (i, j) cell indices within the quad.
Q2DD	`STRUCT(quad UBIGINT, x DOUBLE, y DOUBLE)`	Quad number + continuous (x, y) coordinates within the quad.
PROJTRI	`STRUCT(tnum UBIGINT, x DOUBLE, y DOUBLE)`	Icosahedron triangle number + (x, y) within the projected triangle.
PLANE	`STRUCT(x DOUBLE, y DOUBLE)`	Unfolded icosahedron plane coordinates.
VERTEX2DD	`STRUCT(keep BOOLEAN, vert_num INTEGER, tri_num INTEGER, x DOUBLE, y DOUBLE)`	Vertex-based 2D coordinate with triangle and vertex metadata.

Function Index

Function	Input	Output	Description
`duck_dggs_version`	—	`VARCHAR`	Extension and DGGRID library version.
`dggs_params`	config fields	`STRUCT`	Construct a grid configuration struct.
`geo_to_seqnum`	GEO, res	SEQNUM	GEO → sequential cell index.
`geo_to_geo`	GEO, res	GEO	Snap a point to its DGGS cell centre.
`geo_to_q2di`	GEO, res	Q2DI	GEO → quad/integer index.
`geo_to_q2dd`	GEO, res	Q2DD	GEO → quad/continuous coords.
`geo_to_projtri`	GEO, res	PROJTRI	GEO → projected triangle coords.
`geo_to_plane`	GEO, res	PLANE	GEO → unfolded plane coords.
`seqnum_to_geo`	SEQNUM, res	GEO	Sequential index → cell centre point.
`seqnum_to_boundary`	SEQNUM, res	GEO	Sequential index → cell boundary polygon.
`seqnum_to_seqnum`	SEQNUM, res	SEQNUM	Re-index a cell at the same resolution.
`seqnum_to_q2di`	SEQNUM, res	Q2DI	Sequential index → quad/integer index.
`seqnum_to_q2dd`	SEQNUM, res	Q2DD	Sequential index → quad/continuous coords.
`seqnum_to_projtri`	SEQNUM, res	PROJTRI	Sequential index → projected triangle coords.
`seqnum_to_plane`	SEQNUM, res	PLANE	Sequential index → unfolded plane coords.
`q2di_to_geo`	Q2DI, res	GEO	Quad/integer index → cell centre point.
`q2di_to_seqnum`	Q2DI, res	SEQNUM	Quad/integer index → sequential index.
`q2di_to_q2di`	Q2DI, res	Q2DI	Re-encode a cell in quad/integer form.
`q2di_to_q2dd`	Q2DI, res	Q2DD	Quad/integer index → quad/continuous coords.
`q2di_to_projtri`	Q2DI, res	PROJTRI	Quad/integer index → projected triangle coords.
`q2di_to_plane`	Q2DI, res	PLANE	Quad/integer index → unfolded plane coords.
`q2dd_to_geo`	Q2DD, res	GEO	Quad/continuous coords → cell centre point.
`q2dd_to_seqnum`	Q2DD, res	SEQNUM	Quad/continuous coords → sequential index.
`q2dd_to_q2di`	Q2DD, res	Q2DI	Quad/continuous coords → quad/integer index.
`q2dd_to_q2dd`	Q2DD, res	Q2DD	Re-encode a cell in quad/continuous form.
`q2dd_to_projtri`	Q2DD, res	PROJTRI	Quad/continuous coords → projected triangle coords.
`q2dd_to_plane`	Q2DD, res	PLANE	Quad/continuous coords → unfolded plane coords.
`projtri_to_geo`	PROJTRI, res	GEO	Projected triangle coords → cell centre point.
`projtri_to_seqnum`	PROJTRI, res	SEQNUM	Projected triangle coords → sequential index.
`projtri_to_q2di`	PROJTRI, res	Q2DI	Projected triangle coords → quad/integer index.
`projtri_to_q2dd`	PROJTRI, res	Q2DD	Projected triangle coords → quad/continuous coords.
`projtri_to_projtri`	PROJTRI, res	PROJTRI	Re-encode a cell in projected triangle form.
`projtri_to_plane`	PROJTRI, res	PLANE	Projected triangle coords → unfolded plane coords.
`dggs_n_cells`	res	`UBIGINT`	Number of cells at a given resolution.
`dggs_cell_area_km`	res	`DOUBLE`	Cell area in km² at a given resolution.
`dggs_cell_dist_km`	res	`DOUBLE`	Cell spacing in km at a given resolution.
`dggs_cls_km`	res	`DOUBLE`	Characteristic length scale in km.
`dggs_res_info`	res	`STRUCT`	All grid statistics for a resolution.
`seqnum_neighbors`	SEQNUM, res	`UBIGINT[]`	Topologically adjacent cells.
`seqnum_parent`	SEQNUM, res	`UBIGINT`	Parent cell at res-1.
`seqnum_all_parents`	SEQNUM, res	`UBIGINT[]`	All touching parent cells at res-1.
`seqnum_children`	SEQNUM, res	`UBIGINT[]`	Child cells at res+1.
`seqnum_to_zorder`	SEQNUM, res	`UBIGINT`	Sequential index to Z-order index.
`zorder_to_seqnum`	ZORDER, res	`UBIGINT`	Z-order index to sequential index.
`seqnum_to_z3`	SEQNUM, res	`UBIGINT`	Sequential index to Z3 index (aperture 3).
`z3_to_seqnum`	Z3, res	`UBIGINT`	Z3 index to sequential index.
`seqnum_to_z7`	SEQNUM, res	`UBIGINT`	Sequential index to Z7 index (aperture 7).
`z7_to_seqnum`	Z7, res	`UBIGINT`	Z7 index to sequential index.
`seqnum_to_vertex2dd`	SEQNUM, res	VERTEX2DD	Sequential index to vertex 2DD coords.
`vertex2dd_to_seqnum`	VERTEX2DD, res	`UBIGINT`	Vertex 2DD coords to sequential index.
`igeo7_from_string`	VARCHAR	`UBIGINT`	Parse compact IGEO7/Z7 string → packed index.
`igeo7_to_string`	Z7	`VARCHAR`	Packed index → compact string (stops before first `7`).
`igeo7_encode`	base, d1..d20	`UBIGINT`	Pack base cell + 20 digit slots.
`igeo7_encode_at_resolution`	base, res, d1..d20	`UBIGINT`	Encode then truncate to resolution.
`igeo7_get_resolution`	Z7	`INTEGER`	Resolution (0–20) of a packed index.
`igeo7_get_base_cell`	Z7	`UTINYINT`	Base cell ID (0–11).
`igeo7_get_digit`	Z7, pos	`UTINYINT`	Extract the i-th digit (1–20).
`igeo7_parent`	Z7	`UBIGINT`	Parent index (one level up).
`igeo7_parent_at`	Z7, res	`UBIGINT`	Ancestor at specific resolution.
`igeo7_get_neighbours`	Z7	`UBIGINT[]`	All 6 neighbours (invalid = `UINT64_MAX`).
`igeo7_get_neighbour`	Z7, dir	`UBIGINT`	Single neighbour in direction 1–6.
`igeo7_first_non_zero`	Z7	`INTEGER`	Position of first non-zero digit slot.
`igeo7_is_valid`	Z7	`BOOLEAN`	`FALSE` when index equals `UINT64_MAX` sentinel.
`igeo7_decode_str`	Z7	`VARCHAR`	Verbose `base-d1.d2…d20` form showing all 20 slots.
`igeo7_string_parent`	VARCHAR	`VARCHAR`	Drop last char of a compact IGEO7 string.
`igeo7_string_local_pos`	VARCHAR	`VARCHAR`	Last char of a compact IGEO7 string.
`igeo7_string_is_center`	VARCHAR	`BOOLEAN`	True when last digit is `'0'` (center of parent).
`igeo7_geo_to_authalic`	GEOMETRY	`GEOMETRY`	Remap each vertex's latitude from geodetic → authalic (WGS84).
`igeo7_authalic_to_geo`	GEOMETRY	`GEOMETRY`	Remap each vertex's latitude from authalic → geodetic (WGS84).

Utility Functions

duck_dggs_version

Signature

VARCHAR duck_dggs_version ()

Parameter	Type	Description
`projection`	`VARCHAR`	Projection type. `'ISEA'` (Icosahedral Snyder Equal Area) or `'FULLER'`.
`aperture`	`INTEGER`	Cell aperture (ratio of parent to child cell area). `3`, `4`, or `7`.
`topology`	`VARCHAR`	Cell shape. `'HEXAGON'`, `'TRIANGLE'`, or `'DIAMOND'`.
`azimuth_deg`	`DOUBLE`	Rotation of the icosahedron around the pole axis, in degrees.
`pole_lat_deg`	`DOUBLE`	Latitude of the icosahedron pole, in degrees. Default ISEA: `58.28252559`.
`pole_lon_deg`	`DOUBLE`	Longitude of the icosahedron pole, in degrees. Default ISEA: `11.25`.
`is_aperture_sequence`	`BOOLEAN`	When `true`, uses a mixed-aperture sequence instead of a fixed aperture. Default: `false`.
`aperture_sequence`	`VARCHAR`	A string of digits (`'3'`, `'4'`, `'7'`) defining the aperture at each resolution level. Only used when `is_aperture_sequence` is `true`.