H3 Index Functions

MatrixOne provides a family of H3 index functions for working with Uber H3 hexagonal grid system indices. These functions convert POINT geometries into H3 indices stored as BIGINT UNSIGNED values and support operations such as querying resolution, computing parent indices, retrieving cell centers and hexagonal boundaries, and testing neighbor relationships. H3 cells partition the sphere into hexagons (and 12 pentagons) at resolutions 0 (coarse, approximately 4.3 million km²) through 15 (fine, sub-square-meter).

Syntax

Each H3 index function follows the naming pattern H3_H3Index*(...) and accepts specific argument types as documented in the per-function sections below. Arguments include BIGINT UNSIGNED H3 indices, POINT/POINT32 geometry values, and optional INT resolution parameters.

Arguments

All H3 index functions operate on BIGINT UNSIGNED H3 index values and/or POINT/POINT32 geometry values. NULL arguments produce NULL results. See the individual function descriptions below for the exact argument list and return type of each function.

Function List

Function

Description

H3_H3Index(pt[, resolution])

Returns the H3 index for a POINT geometry.

H3_H3Index_Resolution(h3_index)

Returns the resolution (0-15) of the index.

H3_H3Index_Parent(h3_index[, resolution])

Returns the parent index at the given resolution.

H3_H3Index_Center(h3_index)

Returns the center point of the cell as a POINT.

H3_H3Index_Boundary(h3_index)

Returns the cell boundary as a MULTIPOINT with 6 vertices for a hexagon or 5 for a pentagon.

H3_H3Index_Neighbors(h3_index)

Returns a JSON array of 6 neighbor indices for a hexagon or 5 for a pentagon.

H3_H3Index_AreNeighbors(h3_a, h3_b)

Returns 1 if the cells are neighbors, 0 otherwise.

The British-spelling aliases H3_H3Index_Neighbours and H3_H3Index_AreNeighbours are also accepted and behave identically.

H3_H3Index()

Syntax

H3_H3Index(pt[, resolution])

Arguments

pt: A POINT or POINT32 geometry value. resolution: An optional INT specifying the desired H3 resolution (0-15). If omitted, defaults to 15 (finest).

Return Value

Returns BIGINT UNSIGNED for POINT inputs and BIGINT UNSIGNED for POINT32 inputs. Returns NULL if any argument is NULL.

Usage Notes

  • The point must have longitude in [-180, 180] and latitude in [-90, 90].

  • An empty point (POINT EMPTY) raises an error.

  • Resolution 0 produces the coarsest cells; resolution 15 produces the finest.

H3_H3Index_Resolution()

Syntax

H3_H3Index_Resolution(h3_index)

Arguments

h3_index: A BIGINT UNSIGNED value representing a valid H3 index.

Return Value

Returns INT. The resolution is an integer between 0 and 15 inclusive. Returns NULL if the argument is NULL.

Usage Notes

  • Passing 0 as the H3Index raises an “invalid H3Index” error.

H3_H3Index_Parent()

Syntax

H3_H3Index_Parent(h3_index[, resolution])

Arguments

h3_index: A BIGINT UNSIGNED value representing a valid H3 index. resolution: An optional INT specifying the desired parent resolution. If omitted, defaults to cell_resolution - 1 (one level coarser).

Return Value

Returns BIGINT UNSIGNED. The parent H3 index at the requested resolution. Returns NULL if any argument is NULL.

Usage Notes

  • An H3 index at resolution 0 has no parent; requesting a parent raises an error.

  • The parent resolution must be coarser than (numerically less than) the current cell’s resolution. Requesting a finer or equal resolution raises an error.

H3_H3Index_Center()

Syntax

H3_H3Index_Center(h3_index)

Arguments

h3_index: A BIGINT UNSIGNED value representing a valid H3 index.

Return Value

Returns POINT containing the longitude and latitude of the cell’s center. Returns NULL if the argument is NULL.

H3_H3Index_Boundary()

Syntax

H3_H3Index_Boundary(h3_index)

Arguments

h3_index: A BIGINT UNSIGNED value representing a valid H3 index.

Return Value

Returns MULTIPOINT containing the cell-boundary vertices: 6 for a hexagonal cell or 5 for a pentagonal cell. Returns NULL if the argument is NULL.

H3_H3Index_Neighbors()

Syntax

H3_H3Index_Neighbors(h3_index)

Arguments

h3_index: A BIGINT UNSIGNED value representing a valid H3 index.

Return Value

Returns a JSON array of neighbor H3 indices as BIGINT UNSIGNED values: 6 for a hexagonal cell or 5 for a pentagonal cell. Returns NULL if the argument is NULL.

Usage Notes

  • The British-spelling alias H3_H3Index_Neighbours(h3_index) returns the same result.

H3_H3Index_AreNeighbors()

Syntax

H3_H3Index_AreNeighbors(h3_a, h3_b)

Arguments

h3_a, h3_b: BIGINT UNSIGNED values representing valid H3 indices.

Return Value

Returns TINYINT(1): 1 if the two cells are neighbors at the same resolution, 0 otherwise. Returns NULL if either argument is NULL.

Usage Notes

  • A cell is NOT a neighbor of itself (returns 0).

  • Cells at different resolutions are NOT considered neighbors (returns 0).

  • The relationship is symmetric: if A is a neighbor of B, then B is a neighbor of A.

  • The British-spelling alias H3_H3Index_AreNeighbours(h3_a, h3_b) returns the same result.

Error Cases

The following inputs cause runtime errors:

Condition

Error message

H3Index is 0

invalid input: invalid H3Index: 0

Longitude/latitude out of range

invalid input: longitude/latitude out of range: (lng, lat)

Empty POINT geometry

invalid input: invalid point payload

Resolution 0 cell has no parent

invalid input: H3Index at resolution 0 has no parent

Parent resolution finer than cell resolution

invalid input: parent resolution N is finer than cell resolution M

Examples

DROP DATABASE IF EXISTS dbgeocell;
CREATE DATABASE dbgeocell;
USE dbgeocell;

SELECT H3_H3Index_Resolution(H3_H3Index(ST_GeomFromText('POINT(116.3975 39.9087)'))) AS default_res;

SELECT H3_H3Index_Resolution(H3_H3Index(ST_GeomFromText('POINT(116.3975 39.9087)'), 7)) AS res7;

SELECT ST_AsText(H3_H3Index_Center(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 5))) AS center_point;

SELECT ST_GeometryType(H3_H3Index_Boundary(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 5))) AS boundary_type;

SELECT ST_NumGeometries(H3_H3Index_Boundary(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 5))) AS n_vertices;

SELECT H3_H3Index_Resolution(H3_H3Index_Parent(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7))) AS parent_res;

SELECT H3_H3Index_Resolution(H3_H3Index_Parent(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7), 3)) AS parent_res3;

SELECT JSON_LENGTH(H3_H3Index_Neighbors(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7))) AS n_neighbors;

SELECT H3_H3Index_AreNeighbors(
    H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7),
    H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7)) AS self_not_neighbor;

SELECT H3_H3Index_AreNeighbors(
    c,
    CAST(JSON_UNQUOTE(JSON_EXTRACT(H3_H3Index_Neighbors(c), '$[0]')) AS UNSIGNED)) AS first_is_neighbor
FROM (SELECT H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7) AS c) t;

SELECT H3_H3Index_AreNeighbors(
    H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7),
    H3_H3Index_Parent(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 7), 3)) AS cross_res;

CREATE TABLE h3t(id INT, pt POINT, h3 BIGINT UNSIGNED);
INSERT INTO h3t VALUES (1, ST_GeomFromText('POINT(116.3975 39.9087)'), 0);
INSERT INTO h3t VALUES (2, ST_GeomFromText('POINT(121.4737 31.2304)'), 0);
UPDATE h3t SET h3 = H3_H3Index(pt, 9);
SELECT id, H3_H3Index_Resolution(h3) AS res FROM h3t ORDER BY id;
DROP TABLE IF EXISTS h3t;

SELECT H3_H3Index(NULL) AS a, H3_H3Index(NULL, 9) AS b, H3_H3Index_Resolution(NULL) AS c,
       H3_H3Index_Center(NULL) AS d, H3_H3Index_Boundary(NULL) AS e,
       H3_H3Index_Parent(NULL) AS f, H3_H3Index_Neighbors(NULL) AS g,
       H3_H3Index_AreNeighbors(NULL, NULL) AS h;

-- Expected-Success: false
SELECT H3_H3Index_Resolution(0);

-- Expected-Success: false
SELECT H3_H3Index(ST_GeomFromText('POINT(0 95)'));

-- Expected-Success: false
SELECT H3_H3Index_Parent(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 0));

-- Expected-Success: false
SELECT H3_H3Index_Parent(H3_H3Index(ST_GeomFromText('POINT(0 0)'), 3), 7);

DROP DATABASE dbgeocell;

See Also