用于处理 H3 索引的函数

H3 索引

H3 是一种地理编码系统，地球表面被划分为均匀的六边形网格。该系统是分层的，即每个顶层的六边形（“父级”）可以分割成七个均匀但更小的六边形（“子级”），依此类推。

层次的级别称为 resolution，可以取值从 0 到 15，其中 0 是具有最大和粗糙单元的 base 层级。

一个纬度和经度的组合可以转换为一个 64 位的 H3 索引，用以标识一个网格单元。

H3 索引用于主要的地点分组及其他地理空间操作。

H3 系统的完整介绍，请访问 Uber 工程网站。

h3IsValid

验证该数字是否为有效的 H3 索引。

语法

h3IsValid(h3index)

参数

• h3index — 六边形索引编号。 UInt64。

返回值

• 1 — 该数字是有效的 H3 索引。 UInt8。
• 0 — 该数字不是有效的 H3 索引。 UInt8。

示例

查询：

SELECT h3IsValid(630814730351855103) AS h3IsValid;

结果：

┌─h3IsValid─┐
│         1 │
└───────────┘

h3GetResolution

定义给定的 H3 索引的分辨率。

语法

h3GetResolution(h3index)

参数

• h3index — 六边形索引编号。 UInt64。

返回值

• 索引分辨率。范围: [0, 15]。 UInt8。
• 如果索引无效，函数返回随机值。使用 h3IsValid 验证索引。 UInt8。

示例

查询：

SELECT h3GetResolution(639821929606596015) AS resolution;

结果：

┌─resolution─┐
│         14 │
└────────────┘

h3EdgeAngle

计算 H3 六边形边的平均长度（单位为度）。

语法

h3EdgeAngle(resolution)

参数

• resolution — 索引分辨率。 UInt8。范围: [0, 15]。

返回值

• H3 六边形边的平均长度（单位为度）。 Float64。

示例

查询：

SELECT h3EdgeAngle(10) AS edgeAngle;

结果：

┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘

h3EdgeLengthM

计算 H3 六边形边的平均长度（单位为米）。

语法

h3EdgeLengthM(resolution)

参数

• resolution — 索引分辨率。 UInt8。范围: [0, 15]。

返回值

• H3 六边形边的平均长度（单位为米）。 Float64。

示例

查询：

SELECT h3EdgeLengthM(15) AS edgeLengthM;

结果：

┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘

h3EdgeLengthKm

计算 H3 六边形边的平均长度（单位为千米）。

语法

h3EdgeLengthKm(resolution)

参数

• resolution — 索引分辨率。 UInt8。范围: [0, 15]。

返回值

• H3 六边形边的平均长度（单位为千米）。 Float64。

示例

查询：

SELECT h3EdgeLengthKm(15) AS edgeLengthKm;

结果：

┌─edgeLengthKm─┐
│  0.000509713 │
└──────────────┘

geoToH3

返回给定分辨率的 H3 点索引 (lat, lon)。

语法

geoToH3(lat, lon, resolution)

参数

• lat — 纬度。 Float64。
• lon — 经度。 Float64。
• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 六边形索引编号。 UInt64。
• 错误时返回 0。 UInt64。

注意：在 ClickHouse v25.4 或更早版本中，geoToH3() 按照 (lon, lat) 的顺序接受值。根据 ClickHouse v25.5，输入值按照 (lat, lon) 的顺序。可以使用设置 geotoh3_argument_order = 'lon_lat' 恢复以前的行为。

示例

查询：

SELECT geoToH3(55.71290588, 37.79506683, 15) AS h3Index;

结果：

┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘

h3ToGeo

返回与给定的 H3 索引对应的中心纬度和经度。

语法

h3ToGeo(h3Index)

参数

• h3Index — H3 索引。 UInt64。

返回值

• 一个包含两个值的元组：tuple(lat,lon)。lat — 纬度。 Float64。lon — 经度。 Float64。

注意：在 ClickHouse v24.12 或更早版本中，h3ToGeo() 返回的值按照 (lon, lat) 的顺序。根据 ClickHouse v25.1，返回的值按照 (lat, lon) 的顺序。可以使用设置 h3togeo_lon_lat_result_order = true 恢复以前的行为。

示例

查询：

SELECT h3ToGeo(644325524701193974) AS coordinates;

结果：

┌─coordinates───────────────────────────┐
│ (55.71290243145668,37.79506616830252) │
└───────────────────────────────────────┘

h3ToGeoBoundary

返回一个对应于给定 H3 索引的边界的 (lat, lon) 对数组。

语法

h3ToGeoBoundary(h3Index)

参数

• h3Index — H3 索引。 UInt64。

返回值

• (lat, lon) 对的数组。 Array(Float64, Float64)。

示例

查询：

SELECT h3ToGeoBoundary(644325524701193974) AS coordinates;

结果：

┌─h3ToGeoBoundary(599686042433355775)────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [(37.2713558667319,-121.91508032705622),(37.353926450852256,-121.8622232890249),(37.42834118609435,-121.92354999630156),(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044),(37.26319797461824,-122.02910130919001)] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3kRing

列出距离给定六边形 k 范围内的所有 H3 六边形，顺序为随机。

语法

h3kRing(h3index, k)

参数

• h3index — 六边形索引编号。 UInt64。
• k — 半径。 integer

返回值

• H3 索引数组。 Array(UInt64)。

示例

查询：

SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;

结果：

┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘

h3GetBaseCell

返回 H3 索引的基单元编号。

语法

h3GetBaseCell(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 六边形基单元编号。 UInt8。

示例

查询：

SELECT h3GetBaseCell(612916788725809151) AS basecell;

结果：

┌─basecell─┐
│       12 │
└──────────┘

h3HexAreaM2

返回给定分辨率下的平均六边形面积（单位为平方米）。

语法

h3HexAreaM2(resolution)

参数

• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 面积（单位为平方米）。 Float64。

示例

查询：

SELECT h3HexAreaM2(13) AS area;

结果：

┌─area─┐
│ 43.9 │
└──────┘

h3HexAreaKm2

返回给定分辨率下的平均六边形面积（单位为平方千米）。

语法

h3HexAreaKm2(resolution)

参数

• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 面积（单位为平方千米）。 Float64。

示例

查询：

SELECT h3HexAreaKm2(13) AS area;

结果：

┌──────area─┐
│ 0.0000439 │
└───────────┘

h3IndexesAreNeighbors

返回提供的 H3 索引是否为相邻。

语法

h3IndexesAreNeighbors(index1, index2)

参数

• index1 — 六边形索引编号。 UInt64。
• index2 — 六边形索引编号。 UInt64。

返回值

• 1 — 索引是相邻的。 UInt8。
• 0 — 索引不是相邻的。 UInt8。

示例

查询：

SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;

结果：

┌─n─┐
│ 1 │
└───┘

h3ToChildren

返回给定 H3 索引的子索引数组。

语法

h3ToChildren(index, resolution)

参数

• index — 六边形索引编号。 UInt64。
• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 子 H3 索引的数组。 Array(UInt64)。

示例

查询：

SELECT h3ToChildren(599405990164561919, 6) AS children;

结果：

┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3ToParent

返回包含给定 H3 索引的父级（更粗）的索引。

语法

h3ToParent(index, resolution)

参数

• index — 六边形索引编号。 UInt64。
• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 父 H3 索引。 UInt64。

示例

查询：

SELECT h3ToParent(599405990164561919, 3) AS parent;

结果：

┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘

h3ToString

将索引的 H3Index 表示形式转换为字符串表示形式。

h3ToString(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• H3 索引的字符串表示。 String。

示例

查询：

SELECT h3ToString(617420388352917503) AS h3_string;

结果：

┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘

stringToH3

将字符串表示转换为 H3Index（UInt64）表示。

语法

stringToH3(index_str)

参数

• index_str — H3 索引的字符串表示。 String。

返回值

• 六边形索引编号。错误时返回 0。 UInt64。

示例

查询：

SELECT stringToH3('89184926cc3ffff') AS index;

结果：

┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘

h3GetResolution

返回 H3 索引的分辨率。

语法

h3GetResolution(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 索引分辨率。范围: [0, 15]。 UInt8。

示例

查询：

SELECT h3GetResolution(617420388352917503) AS res;

结果：

┌─res─┐
│   9 │
└─────┘

h3IsResClassIII

返回 H3 索引是否具有 Class III 定向的分辨率。

语法

h3IsResClassIII(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 1 — 索引具有 Class III 定向的分辨率。 UInt8。
• 0 — 索引没有 Class III 定向的分辨率。 UInt8。

示例

查询：

SELECT h3IsResClassIII(617420388352917503) AS res;

结果：

┌─res─┐
│   1 │
└─────┘

h3IsPentagon

返回该 H3 索引是否表示五边形单元。

语法

h3IsPentagon(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 1 — 索引表示五边形单元。 UInt8。
• 0 — 索引不表示五边形单元。 UInt8。

示例

查询：

SELECT h3IsPentagon(644721767722457330) AS pentagon;

结果：

┌─pentagon─┐
│        0 │
└──────────┘

h3GetFaces

返回与给定 H3 索引相交的二十面体面。

语法

h3GetFaces(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 包含与给定 H3 索引相交的二十面体面的数组。 Array(UInt64)。

示例

查询：

SELECT h3GetFaces(599686042433355775) AS faces;

结果：

┌─faces─┐
│ [7]   │
└───────┘

h3CellAreaM2

返回与给定输入 H3 索引相对应的特定单元的确切面积（单位为平方米）。

语法

h3CellAreaM2(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 单元面积（单位为平方米）。 Float64。

示例

查询：

SELECT h3CellAreaM2(579205133326352383) AS area;

结果：

┌───────────────area─┐
│ 4106166334463.9233 │
└────────────────────┘

h3CellAreaRads2

返回与给定输入 H3 索引相对应的特定单元的确切面积（单位为平方弧度）。

语法

h3CellAreaRads2(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 单元面积（单位为平方弧度）。 Float64。

示例

查询：

SELECT h3CellAreaRads2(579205133326352383) AS area;

结果：

┌────────────────area─┐
│ 0.10116268528089567 │
└─────────────────────┘

h3ToCenterChild

返回包含给定分辨率下的给定 H3 的中心子索引（更细）。

语法

h3ToCenterChild(index, resolution)

参数

• index — 六边形索引编号。 UInt64。
• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 在给定分辨率下包含的中心子索引的 H3。 UInt64。

示例

查询：

SELECT h3ToCenterChild(577023702256844799,1) AS centerToChild;

结果：

┌──────centerToChild─┐
│ 581496515558637567 │
└────────────────────┘

h3ExactEdgeLengthM

返回表示输入 h3 索引的单向边的确切边长（单位为米）。

语法

h3ExactEdgeLengthM(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 确切边长（单位为米）。 Float64。

示例

查询：

SELECT h3ExactEdgeLengthM(1310277011704381439) AS exactEdgeLengthM;;

结果：

┌───exactEdgeLengthM─┐
│ 195449.63163407316 │
└────────────────────┘

h3ExactEdgeLengthKm

返回表示输入 h3 索引的单向边的确切边长（单位为千米）。

语法

h3ExactEdgeLengthKm(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 确切边长（单位为千米）。 Float64。

示例

查询：

SELECT h3ExactEdgeLengthKm(1310277011704381439) AS exactEdgeLengthKm;;

结果：

┌──exactEdgeLengthKm─┐
│ 195.44963163407317 │
└────────────────────┘

h3ExactEdgeLengthRads

返回表示输入 h3 索引的单向边的确切边长（单位为弧度）。

语法

h3ExactEdgeLengthRads(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 确切边长（单位为弧度）。 Float64。

示例

查询：

SELECT h3ExactEdgeLengthRads(1310277011704381439) AS exactEdgeLengthRads;;

结果：

┌──exactEdgeLengthRads─┐
│ 0.030677980118976447 │
└──────────────────────┘

h3NumHexagons

返回给定分辨率下唯一 H3 索引的数量。

语法

h3NumHexagons(resolution)

参数

• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• H3 索引的数量。 Int64。

示例

查询：

SELECT h3NumHexagons(3) AS numHexagons;

结果：

┌─numHexagons─┐
│       41162 │
└─────────────┘

h3PointDistM

返回成对 GeoCoord 点（纬度/经度）之间的“大圆”或“哈弗辛”距离（单位为米）。

语法

h3PointDistM(lat1, lon1, lat2, lon2)

参数

• lat1, lon1 — 第一个点的纬度和经度（单位为度）。 Float64。
• lat2, lon2 — 第二个点的纬度和经度（单位为度）。 Float64。

返回值

• 哈弗辛或大圆距离（单位为米）。 Float64。

示例

查询：

SELECT h3PointDistM(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistM;

结果：

┌──────h3PointDistM─┐
│ 2223901.039504589 │
└───────────────────┘

h3PointDistKm

返回成对 GeoCoord 点（纬度/经度）之间的“大圆”或“哈弗辛”距离（单位为千米）。

语法

h3PointDistKm(lat1, lon1, lat2, lon2)

参数

• lat1, lon1 — 第一个点的纬度和经度（单位为度）。 Float64。
• lat2, lon2 — 第二个点的纬度和经度（单位为度）。 Float64。

返回值

• 哈弗辛或大圆距离（单位为千米）。 Float64。

示例

查询：

SELECT h3PointDistKm(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistKm;

结果：

┌─────h3PointDistKm─┐
│ 2223.901039504589 │
└───────────────────┘

h3PointDistRads

返回成对 GeoCoord 点（纬度/经度）之间的“大圆”或“哈弗辛”距离（单位为弧度）。

语法

h3PointDistRads(lat1, lon1, lat2, lon2)

参数

• lat1, lon1 — 第一个点的纬度和经度（单位为度）。 Float64。
• lat2, lon2 — 第二个点的纬度和经度（单位为度）。 Float64。

返回值

• 哈弗辛或大圆距离（单位为弧度）。 Float64。

示例

查询：

SELECT h3PointDistRads(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistRads;

结果：

┌────h3PointDistRads─┐
│ 0.3490658503988659 │
└────────────────────┘

h3GetRes0Indexes

返回所有分辨率为 0 的 H3 索引的数组。

语法

h3GetRes0Indexes()

返回值

• 所有分辨率为 0 的 H3 索引的数组。 Array(UInt64)。

示例

查询：

SELECT h3GetRes0Indexes AS indexes ;

结果：

┌─indexes─────────────────────────────────────┐
│ [576495936675512319,576531121047601151,....]│
└─────────────────────────────────────────────┘

h3GetPentagonIndexes

返回指定分辨率的所有五边形 H3 索引。

语法

h3GetPentagonIndexes(resolution)

参数

• resolution — 索引分辨率。范围: [0, 15]。 UInt8。

返回值

• 所有五边形 H3 索引的数组。 Array(UInt64)。

示例

查询：

SELECT h3GetPentagonIndexes(3) AS indexes;

结果：

┌─indexes────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘

h3Line

返回两个提供的索引之间的索引线。

语法

h3Line(start,end)

参数

• start — 表示起始点的六边形索引编号。 UInt64。
• end — 表示结束点的六边形索引编号。 UInt64。

返回值

表示两个提供的索引之间的索引线的 H3 索引数组。 Array(UInt64)。

示例

查询：

SELECT h3Line(590080540275638271,590103561300344831) AS indexes;

结果：

┌─indexes────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3Distance

返回提供的两个索引之间的网格单元距离。

语法

h3Distance(start,end)

参数

• start — 表示起始点的六边形索引编号。 UInt64。
• end — 表示结束点的六边形索引编号。 UInt64。

返回值

• 网格单元的数量。 Int64。

如果查找距离失败，则返回负数。

示例

查询：

SELECT h3Distance(590080540275638271,590103561300344831) AS distance;

结果：

┌─distance─┐
│        7 │
└──────────┘

h3HexRing

返回以给定原点 h3Index 为中心、长度为 k 的六边形环的索引。

如果没有遇到五边形畸变，则返回 0。

语法

h3HexRing(index, k)

参数

• index — 表示原点的六边形索引编号。 UInt64。
• k — 距离。 UInt64。

返回值

• H3 索引数组。 Array(UInt64)。

示例

查询：

SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;

结果：

┌─hexRing─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3GetUnidirectionalEdge

根据提供的原点和目的地返回一个单向边 H3 索引，并在错误时返回 0。

语法

h3GetUnidirectionalEdge(originIndex, destinationIndex)

参数

• originIndex — 原点六边形索引编号。 UInt64。
• destinationIndex — 目的地六边形索引编号。 UInt64。

返回值

• 单向边六边形索引编号。 UInt64。

示例

查询：

SELECT h3GetUnidirectionalEdge(599686042433355775, 599686043507097599) AS edge;

结果：

┌────────────────edge─┐
│ 1248204388774707199 │
└─────────────────────┘

h3UnidirectionalEdgeIsValid

确定提供的 H3Index 是否为有效的单向边索引。如果是单向边则返回 1，否则返回 0。

语法

h3UnidirectionalEdgeisValid(index)

参数

• index — 六边形索引编号。 UInt64。

返回值

• 1 — H3 索引是有效的单向边。 UInt8。
• 0 — H3 索引不是有效的单向边。 UInt8。

示例

查询：

SELECT h3UnidirectionalEdgeIsValid(1248204388774707199) AS validOrNot;

结果：

┌─validOrNot─┐
│          1 │
└────────────┘

h3GetOriginIndexFromUnidirectionalEdge

返回单向边 H3Index 的原点六边形索引。

语法

h3GetOriginIndexFromUnidirectionalEdge(edge)

参数

• edge — 表示单向边的六边形索引编号。 UInt64。

返回值

• 原点六边形索引编号。 UInt64。

示例

查询：

SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707197) AS origin;

结果：

┌─────────────origin─┐
│ 599686042433355773 │
└────────────────────┘

h3GetDestinationIndexFromUnidirectionalEdge

返回单向边 H3Index 的目的地六边形索引。

语法

h3GetDestinationIndexFromUnidirectionalEdge(edge)

参数

• edge — 表示单向边的六边形索引编号。 UInt64。

返回值

• 目的地六边形索引编号。 UInt64。

示例

查询：

SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707197) AS destination;

结果：

┌────────destination─┐
│ 599686043507097597 │
└────────────────────┘

h3GetIndexesFromUnidirectionalEdge

从给定的单向边 H3Index 返回原点和目的地六边形索引。

语法

h3GetIndexesFromUnidirectionalEdge(edge)

参数

• edge — 表示单向边的六边形索引编号。 UInt64。

返回值

包含两个值的元组 tuple(origin,destination)：

• origin — 原点六边形索引编号。 UInt64。
• destination — 目的地六边形索引编号。 UInt64。

如果提供的输入无效，则返回 (0,0)。

示例

查询：

SELECT h3GetIndexesFromUnidirectionalEdge(1248204388774707199) AS indexes;

结果：

┌─indexes─────────────────────────────────┐
│ (599686042433355775,599686043507097599) │
└─────────────────────────────────────────┘

h3GetUnidirectionalEdgesFromHexagon

提供来自给定 H3Index 的所有单向边。

语法

h3GetUnidirectionalEdgesFromHexagon(index)

参数

• index — 表示单向边的六边形索引编号。 UInt64。

返回值

表示每个单向边的 H3 索引数组。 Array(UInt64)。

示例

查询：

SELECT h3GetUnidirectionalEdgesFromHexagon(1248204388774707199) AS edges;

结果：

┌─edges─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [1248204388774707199,1320261982812635135,1392319576850563071,1464377170888491007,1536434764926418943,1608492358964346879] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3GetUnidirectionalEdgeBoundary

返回定义单向边的坐标。

语法

h3GetUnidirectionalEdgeBoundary(index)

参数

• index — 表示单向边的六边形索引编号。 UInt64。

返回值

• (lon, lat) 对的数组。 Array(Float64, Float64)。

示例

查询：

SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) AS boundary;

结果：

┌─boundary────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘