Set up docs MCPH3 索引
H3 是一种地理空间索引系统，它将地球表面划分为由大小一致的六边形单元组成的网格。该系统具有层级结构，也就是说，顶层的每个六边形 (“父级”) 都可以细分为七个同样规则但更小的六边形 (“子级”) ，以此类推。
该层级称为 resolution，取值范围为 0 到 15，其中 0 是 base 级别，对应最大且最粗粒度的单元。
一组纬度和经度坐标可以转换为一个 64 位 H3 index，用于标识某个网格单元。
H3 index 主要用于对位置进行分桶以及其他地理空间操作。
有关 H3 系统的完整说明，请参阅 Uber Engineering 网站。
h3IsValid
检查该数字是否为有效的 H3 索引。
语法
h3IsValid(h3index)参数
h3index— 六边形索引编号。UInt64。
返回值
示例
SELECT h3IsValid(630814730351855103) AS h3IsValid;┌─h3IsValid─┐
│ 1 │
└───────────┘h3GetResolution
返回给定 H3 索引的分辨率。
语法
h3GetResolution(h3index)参数
h3index— 六边形索引编号。UInt64。
返回值
示例
SELECT h3GetResolution(639821929606596015) AS resolution;┌─resolution─┐
│ 14 │
└────────────┘h3EdgeAngle
计算 H3 六边形边的平均角长度 (以百分度为单位) 。
语法
h3EdgeAngle(resolution)参数
resolution— 索引分辨率。UInt8。范围：[0, 15]。
返回值
示例
SELECT h3EdgeAngle(10) AS edgeAngle;┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘h3EdgeLengthM
计算 H3 六边形边长的平均值，单位为米。
语法
h3EdgeLengthM(resolution)参数
resolution— 索引分辨率。UInt8。取值范围：[0, 15]。
返回值
示例
SELECT h3EdgeLengthM(15) AS edgeLengthM;┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘h3EdgeLengthKm
计算 H3 六边形边长的平均值，单位为千米。
语法
h3EdgeLengthKm(resolution)参数
resolution— 索引分辨率。UInt8。取值范围：[0, 15]。
返回值
示例
SELECT h3EdgeLengthKm(15) AS edgeLengthKm;┌─edgeLengthKm─┐
│ 0.000509713 │
└──────────────┘geoToH3
返回具有指定分辨率的 H3 点索引 (lat, lon)。
语法
geoToH3(lat, lon, resolution)参数
返回值
注意：在 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。
返回值
注意：在 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
返回由 (lat, lon) 对组成的数组，对应于给定 H3 索引的边界。
语法
h3ToGeoBoundary(h3Index)参数
h3Index— H3 索引。UInt64。
返回值
示例
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)参数
返回值
示例
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘h3PolygonToCells
返回给定几何体 (Ring 或 (多) Polygon) 所包含的指定分辨率六边形单元。
语法
h3PolygonToCells(geometry, resolution)参数
返回值
示例
SELECT h3PolygonToCells([(-122.4089866999972145,37.813318999983238),(-122.3544736999993603,37.7198061999978478),(-122.4798767000009008,37.8151571999998453)], 7) AS h3index;┌────────────h3index─┐
│ 608692970769612799 │
│ 608692971927240703 │
│ 608692970585063423 │
│ 608692970819944447 │
│ 608692970719281151 │
│ 608692970752835583 │
│ 608692972027903999 │
└────────────────────┘h3PolygonToCellsWithContainment
使用 H3 Experimental 包含模式，返回覆盖给定几何体 (Ring 或 (多) Polygon) 且具有指定分辨率的六边形单元。
此函数将 flags 映射为 H3 包含模式：
0—CONTAINMENT_CENTER1—CONTAINMENT_FULL2—CONTAINMENT_OVERLAPPING3—CONTAINMENT_OVERLAPPING_BBOX
语法
h3PolygonToCellsWithContainment(geometry, resolution, flags)参数
geometry可以是以下 Geo 数据类型 之一，或其底层基本类型：resolution— 索引分辨率。范围：[0, 15]。UInt8。flags— 包含模式。范围：[0, 3]。使用整数字面量，例如0、1、2和3，或 UInt32 值 (例如toUInt32(2)) 。这些值会作为UInt32传递给 H3 API。其他原生整数类型会通过精确类型转换进行转换。
返回值
示例
SELECT
h3PolygonToCellsWithContainment([(-122.4089866999972145, 37.813318999983238), (-122.3544736999993603, 37.7198061999978478), (-122.4798767000009008, 37.8151571999998453)], 7, 0) AS center_cells,
h3PolygonToCellsWithContainment([(-122.4089866999972145, 37.813318999983238), (-122.3544736999993603, 37.7198061999978478), (-122.4798767000009008, 37.8151571999998453)], 7, 2) AS overlap_cells; ┌─center_cells───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─overlap_cells──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
1. │ [608692970585063423,608692970719281151,608692970752835583,608692970769612799,608692970819944447,608692971927240703,608692972027903999] │ [608692970249519103,608692970266296319,608692970585063423,608692970601840639,608692970635395071,608692970685726719,608692970719281151,608692970736058367,608692970752835583,608692970769612799,608692970786390015,608692970819944447,608692971927240703,608692971994349567,608692972027903999] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘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)参数
返回值
示例
SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;┌─n─┐
│ 1 │
└───┘h3ToChildren
返回指定 H3 索引的子索引数组。
语法
h3ToChildren(index, resolution)参数
返回值
示例
SELECT h3ToChildren(599405990164561919, 6) AS children;┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘h3ToParent
返回包含给定 H3 索引的父索引 (较粗粒度) 。
语法
h3ToParent(index, resolution)参数
返回值
- 父级 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。
返回值
示例
SELECT h3IsResClassIII(617420388352917503) AS res;┌─res─┐
│ 1 │
└─────┘h3IsPentagon
返回此 H3 索引是否表示五边形单元。
语法
h3IsPentagon(index)参数
index— 六边形索引编号。UInt64。
返回值
示例
SELECT h3IsPentagon(644721767722457330) AS pentagon;┌─pentagon─┐
│ 0 │
└──────────┘h3GetFaces
返回与给定 H3 索引相交的二十面体各面。
语法
h3GetFaces(index)参数
index— 六边形索引编号。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 在指定分辨率下包含的中心子 (更细粒度) H3 索引。
语法
h3ToCenterChild(index, resolution)参数
返回值
示例
SELECT h3ToCenterChild(577023702256844799,1) AS centerToChild;┌──────centerToChild─┐
│ 581496515558637567 │
└────────────────────┘h3ExactEdgeLengthM
返回输入 h3 索引所表示的单向边的精确长度，单位为米。
语法
h3ExactEdgeLengthM(index)参数
index— 六边形索引编号。UInt64
返回值
- 精确边长，单位为米。Float64
示例
SELECT round(h3ExactEdgeLengthM(1310277011704381439), 6) AS exactEdgeLengthM;┌─exactEdgeLengthM─┐
│ 195449.631634 │
└──────────────────┘h3ExactEdgeLengthKm
返回输入 h3 索引所表示的单向边的精确长度，单位为千米。
语法
h3ExactEdgeLengthKm(index)参数
index— 六边形索引编号。UInt64。
返回值
- 以千米为单位的精确边长。Float64。
示例
SELECT round(h3ExactEdgeLengthKm(1310277011704381439), 8) AS exactEdgeLengthKm;┌─exactEdgeLengthKm─┐
│ 195.44963163 │
└───────────────────┘h3ExactEdgeLengthRads
返回输入的 h3 索引所表示的单向边的精确长度，单位为弧度。
语法
h3ExactEdgeLengthRads(index)参数
index— 六边形索引编号。UInt64。
返回值
- 以弧度表示的精确边长。Float64。
示例
SELECT round(h3ExactEdgeLengthRads(1310277011704381439), 12) AS exactEdgeLengthRads;┌─exactEdgeLengthRads─┐
│ 0.030677980119 │
└─────────────────────┘h3NumHexagons
返回指定分辨率下唯一 H3 索引的数量。
语法
h3NumHexagons(resolution)参数
resolution— 索引分辨率。取值范围：[0, 15]。UInt8。
返回值
- H3 索引数量。Int64。
示例
SELECT h3NumHexagons(3) AS numHexagons;┌─numHexagons─┐
│ 41162 │
└─────────────┘h3PointDistM
返回成对的 GeoCoord 点 (纬度/经度) 之间以米为单位的“大圆”或“半正矢”距离。
语法
h3PointDistM(lat1, lon1, lat2, lon2)参数
返回值
- 半正矢距离 (或大圆距离) ，单位为米。Float64。
示例
SELECT h3PointDistM(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistM;┌───────h3PointDistM─┐
│ 2223901.0395045886 │
└────────────────────┘h3PointDistKm
返回成对 GeoCoord 点 (纬度/经度) 之间的“大圆”或“半正矢”距离，单位为千米。
语法
h3PointDistKm(lat1, lon1, lat2, lon2)参数
返回值
- 半正矢 (大圆) 距离，单位为千米。Float64。
示例
SELECT h3PointDistKm(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistKm;┌──────h3PointDistKm─┐
│ 2223.9010395045884 │
└────────────────────┘h3PointDistRads
返回成对 GeoCoord 点 (纬度/经度) 之间的“大圆”距离或“半正矢”距离，结果以弧度表示。
语法
h3PointDistRads(lat1, lon1, lat2, lon2)参数
返回值
- 以弧度为单位的半正矢距离或大圆距离。Float64。
示例
SELECT h3PointDistRads(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistRads;┌────h3PointDistRads─┐
│ 0.3490658503988659 │
└────────────────────┘h3GetRes0Indexes
返回包含所有分辨率 0 的 H3 索引的数组。
语法
h3GetRes0Indexes()返回值
示例
SELECT h3GetRes0Indexes AS indexes ;┌─indexes─────────────────────────────────────┐
│ [576495936675512319,576531121047601151,....]│
└─────────────────────────────────────────────┘h3GetPentagonIndexes
返回指定分辨率的所有五边形 H3 索引。
语法
h3GetPentagonIndexes(resolution)参数
resolution— 索引分辨率。取值范围：[0, 15]。UInt8。
返回值
示例
SELECT h3GetPentagonIndexes(3) AS indexes;┌─indexes────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘h3Line
返回所提供的两个索引之间的连线上的索引。
语法
h3Line(start,end)参数
返回值
由 H3 索引组成的数组，表示两个给定索引之间的索引连线。Array(UInt64)。
示例
SELECT h3Line(590080540275638271,590103561300344831) AS indexes;┌─indexes────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘h3Distance
返回所提供的两个索引之间的距离，单位为网格单元。
语法
h3Distance(start,end)参数
返回值
- 网格单元数量。Int64。
如果无法计算距离，则返回负数。
示例
SELECT h3Distance(590080540275638271,590103561300344831) AS distance;┌─distance─┐
│ 6 │
└──────────┘h3HexRing
返回以给定的 origin h3Index 为中心、长度为 k 的六边形环上的索引。
如果未遇到五边形畸变，则返回 0。
语法
h3HexRing(index, k)参数
返回值
示例
SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;┌─hexRing─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘h3GetUnidirectionalEdge
返回两个相邻 H3 单元索引 (起点和终点) 对应的单向边 H3 index。如果任一输入不是有效的 H3 单元，将抛出异常 (由 functions_h3_default_if_invalid 设置控制) 。对于有效但不相邻的单元 (包括两次传入同一单元) ，返回 0。
语法
h3GetUnidirectionalEdge(originIndex, destinationIndex)参数
返回值
- 单向边的六边形索引编号。UInt64。
示例
SELECT h3GetUnidirectionalEdge(599686042433355775, 599686043507097599) AS edge;┌────────────────edge─┐
│ 1248204388774707199 │
└─────────────────────┘h3UnidirectionalEdgeIsValid
判断给定的 H3Index 是否为有效的单向边索引。如果是单向边，则返回 1，否则返回 0。
语法
h3UnidirectionalEdgeIsValid(index)参数
index— 六边形索引编号。UInt64。
返回值
示例
SELECT h3UnidirectionalEdgeIsValid(1248204388774707199) AS validOrNot;┌─validOrNot─┐
│ 1 │
└────────────┘h3GetOriginIndexFromUnidirectionalEdge
返回单向边 H3Index 对应的起点六边形索引。如果输入不是有效的有向边，则会抛出异常 (由 functions_h3_default_if_invalid 设置控制) ；仅当该设置启用时才返回 0。
语法
h3GetOriginIndexFromUnidirectionalEdge(edge)参数
edge— 表示单向边的六边形索引编号。UInt64.
返回值
- 起点六边形索引编号。UInt64.
- 默认情况下，无效的定向边会抛出
INCORRECT_DATA；当functions_h3_default_if_invalid = 1时返回0。
示例
SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707199) AS origin;┌─────────────origin─┐
│ 599686042433355775 │
└────────────────────┘h3GetDestinationIndexFromUnidirectionalEdge
返回单向边 H3Index 对应的目标六边形索引。如果输入不是有效的有向边，则会引发异常 (由 functions_h3_default_if_invalid 设置控制) ；仅当该设置启用时才返回 0。
语法
h3GetDestinationIndexFromUnidirectionalEdge(edge)参数
edge— 表示单向边的六边形索引编号。UInt64。
返回值
- 终点六边形索引编号。UInt64。
- 对于无效的有向边，默认抛出
INCORRECT_DATA；当functions_h3_default_if_invalid = 1时返回0。
示例
SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707199) AS destination;┌────────destination─┐
│ 599686043507097599 │
└────────────────────┘h3GetIndexesFromUnidirectionalEdge
返回给定单向边 H3Index 对应的起点和终点六边形索引。
语法
h3GetIndexesFromUnidirectionalEdge(edge)参数
edge— 表示单向边的六边形索引编号。UInt64。
返回值
一个由两个值组成的元组 tuple(origin,destination)：
如果提供的输入不是有效的有向边，则会引发异常 (由 functions_h3_default_if_invalid 设置控制) ；仅当启用该设置时才返回 (0,0)。
示例
SELECT h3GetIndexesFromUnidirectionalEdge(1248204388774707199) AS indexes;┌─indexes─────────────────────────────────┐
│ (599686042433355775,599686043507097599) │
└─────────────────────────────────────────┘h3GetUnidirectionalEdgesFromHexagon
返回给定 H3Index 的所有单向边。如果输入不是有效的 H3 单元，则会引发异常 (由 functions_h3_default_if_invalid 设置控制) ；仅当该设置启用时，才返回空数组。
语法
h3GetUnidirectionalEdgesFromHexagon(index)参数
index— 表示单元的六边形索引编号。UInt64。
返回值
- 由表示各条单向边的 H3 索引组成的数组。Array(UInt64)。
- 默认情况下，无效单元会抛出
INCORRECT_DATA；当functions_h3_default_if_invalid = 1时返回[]。
示例
SELECT h3GetUnidirectionalEdgesFromHexagon(599686042433355775) AS edges;┌─edges─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [1248204388774707199,1320261982812635135,1392319576850563071,1464377170888491007,1536434764926418943,1608492358964346879] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘h3GetUnidirectionalEdgeBoundary
返回定义该单向边的坐标。如果输入不是有效的有向边，则会引发异常 (由 functions_h3_default_if_invalid 设置控制) ；仅当该设置已启用时才返回空数组。
语法
h3GetUnidirectionalEdgeBoundary(index)参数
index— 表示单向边的六边形索引编号。UInt64。
返回值
- 由 '(lat, lon)' 对组成的数组。Array(Float64, Float64)。
- 默认情况下，无效的单向边会抛出
INCORRECT_DATA；当functions_h3_default_if_invalid = 1时返回[]。
示例
SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) AS boundary;┌─boundary────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘