H3 索引函数¶
MatrixOne 提供了一系列 H3 索引函数，用于操作 Uber H3 网格系统的索引。这些函数将 POINT 几何值转换为以 BIGINT UNSIGNED 存储的 H3 索引值，并支持查询分辨率、计算父索引、获取单元中心点和边界，以及检测邻接关系。H3 单元将球面划分为六边形（以及 12 个五边形），分辨率从 0（粗粒度，约 430 万 km²）到 15（细粒度，亚平方米级）。
Syntax¶
各 H3 索引函数遵循 H3_H3Index*(...) 命名模式，接受 BIGINT UNSIGNED H3 索引值、POINT/POINT32 几何值以及可选的 INT 分辨率参数。具体语法参见下方各函数说明。
Arguments¶
所有 H3 索引函数均操作 BIGINT UNSIGNED H3 索引值和/或 POINT/POINT32 几何值。NULL 参数产生 NULL 结果。各函数的具体参数列表和返回类型请参见下方函数描述。
函数列表¶
函数 |
描述 |
|---|---|
|
返回 POINT 几何值对应的 H3 索引。 |
|
返回索引的分辨率（0-15）。 |
|
返回指定分辨率的父索引。 |
|
返回单元的中心点，类型为 POINT。 |
|
返回单元边界，类型为 MULTIPOINT；六边形包含 6 个顶点，五边形包含 5 个顶点。 |
|
返回邻居索引的 JSON 数组；六边形有 6 个邻居，五边形有 5 个邻居。 |
|
若两单元为邻居关系返回 1，否则返回 0。 |
英式拼写别名 H3_H3Index_Neighbours 和 H3_H3Index_AreNeighbours 同样被接受，行为完全一致。
H3_H3Index()¶
语法¶
H3_H3Index(pt[, resolution])
参数说明¶
pt：POINT 或 POINT32 几何值。resolution：可选 INT，指定期望的 H3 分辨率（0-15）。若省略，默认为 15（最精细）。
返回值¶
POINT 输入返回 BIGINT UNSIGNED；POINT32 输入返回 BIGINT UNSIGNED。若任一参数为 NULL 则返回 NULL。
使用说明¶
点的经度必须在
[-180, 180]范围内，纬度必须在[-90, 90]范围内。空点（
POINT EMPTY）会导致报错。分辨率
0生成最粗的单元；分辨率15生成最精细的单元。
H3_H3Index_Resolution()¶
语法¶
H3_H3Index_Resolution(h3_index)
参数说明¶
h3_index：表示有效 H3 索引的 BIGINT UNSIGNED 值。
返回值¶
返回 INT。分辨率为 0 到 15 之间的整数（含 0 和 15）。若参数为 NULL 则返回 NULL。
使用说明¶
传入
0作为 H3Index 会导致”invalid H3Index”错误。
H3_H3Index_Parent()¶
语法¶
H3_H3Index_Parent(h3_index[, resolution])
参数说明¶
h3_index：表示有效 H3 索引的 BIGINT UNSIGNED 值。resolution：可选 INT，指定期望的父索引分辨率。若省略，默认值为 cell_resolution - 1（粗一个分辨率级别）。
返回值¶
返回 BIGINT UNSIGNED，为指定分辨率的父 H3 索引。若任一参数为 NULL 则返回 NULL。
使用说明¶
分辨率 0 的 H3 索引无父索引，请求父索引会导致报错。
父索引分辨率必须比当前单元分辨率更粗（数值上更小）。请求更细或相同分辨率会导致报错。
H3_H3Index_Center()¶
语法¶
H3_H3Index_Center(h3_index)
参数说明¶
h3_index：表示有效 H3 索引的 BIGINT UNSIGNED 值。
返回值¶
返回 POINT，包含单元中心的经度和纬度。若参数为 NULL 则返回 NULL。
H3_H3Index_Boundary()¶
语法¶
H3_H3Index_Boundary(h3_index)
参数说明¶
h3_index：表示有效 H3 索引的 BIGINT UNSIGNED 值。
返回值¶
返回 MULTIPOINT，其中六边形单元边界包含 6 个顶点，五边形单元边界包含 5 个顶点。若参数为 NULL 则返回 NULL。
H3_H3Index_Neighbors()¶
语法¶
H3_H3Index_Neighbors(h3_index)
参数说明¶
h3_index：表示有效 H3 索引的 BIGINT UNSIGNED 值。
返回值¶
返回 JSON 数组，其中包含表示邻居 H3 索引的 BIGINT UNSIGNED 值；六边形单元有 6 个邻居，五边形单元有 5 个邻居。若参数为 NULL 则返回 NULL。
使用说明¶
英式拼写别名
H3_H3Index_Neighbours(h3_index)返回相同结果。
H3_H3Index_AreNeighbors()¶
语法¶
H3_H3Index_AreNeighbors(h3_a, h3_b)
参数说明¶
h3_a、h3_b：表示有效 H3 索引的 BIGINT UNSIGNED 值。
返回值¶
返回 TINYINT(1)：若两单元在同一分辨率下为邻居关系返回 1，否则返回 0。若任一参数为 NULL 则返回 NULL。
使用说明¶
一个单元不是自身的邻居（返回 0）。
不同分辨率的单元不被视为邻居（返回 0）。
该关系具有对称性：若 A 是 B 的邻居，则 B 也是 A 的邻居。
英式拼写别名
H3_H3Index_AreNeighbours(h3_a, h3_b)返回相同结果。
错误场景¶
以下输入会导致运行时错误：
情形 |
错误消息 |
|---|---|
H3Index 为 |
|
经度/纬度超出范围 |
|
空 POINT 几何值 |
|
分辨率 0 单元无父索引 |
|
父索引分辨率比当前单元分辨率更细 |
|
示例¶
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;