H3 索引
H3 是一种地理空间索引系统,将地球表面划分为等大的六边形网格单元。该系统是分层的,即顶层的每个六边形(“父”)可以被划分为七个更小但同样等大的六边形(“子”),以此类推。
该分层级别称为 resolution,取值范围为 0 到 15,其中 0 为具有最大、最粗粒度单元的 base 层级。
一组纬度、经度坐标可以被转换为一个 64 位的 H3 索引,用于标识一个网格单元。
H3 索引主要用于对地理位置进行分桶(bucketing)以及其他地理空间操作。
关于 H3 系统的完整说明可在 Uber Engineering 网站 上找到。
h3IsValid
检查给定数值是否为有效的 H3 索引。
语法
参数
返回值
- 1 — 该数值是有效的 H3 索引。UInt8。
- 0 — 该数值不是有效的 H3 索引。UInt8。
示例
查询:
SELECT h3IsValid(630814730351855103) AS h3IsValid;
结果:
┌─h3IsValid─┐
│ 1 │
└───────────┘
h3GetResolution
返回给定 H3 索引的分辨率。
语法
参数
返回值
示例
查询:
SELECT h3GetResolution(639821929606596015) AS resolution;
结果:
┌─resolution─┐
│ 14 │
└────────────┘
h3EdgeAngle
计算 H3 六边形边长以角度制表示的平均值。
语法
参数
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
返回指定分辨率下 (lat, lon) 点的 H3 索引。
语法
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 索引对应的中心点纬度和经度。
语法
参数
返回值
注意:在 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 索引的边界。
语法
参数
返回值
示例
查询:
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 六边形。
语法
参数
返回值
示例
查询:
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;
结果:
┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘
h3PolygonToCells
返回在指定分辨率下位于给定几何体(环或(多)多边形)内的六边形单元。
语法
h3PolygonToCells(geometry, resolution)
参数
geometry 可以是以下任一Geo 数据类型或其底层基础类型:
resolution — 索引分辨率。取值范围:[0, 15]。UInt8。
返回值
示例
查询:
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 │
└────────────────────┘
h3GetBaseCell
返回 H3 索引的基础单元编号。
语法
参数
返回值
示例
查询:
SELECT h3GetBaseCell(612916788725809151) AS basecell;
结果:
┌─basecell─┐
│ 12 │
└──────────┘
h3HexAreaM2
返回在给定分辨率下的六边形平均面积(以平方米计)。
语法
参数
resolution — 索引精度。范围:[0, 15]。UInt8。
返回值
示例
查询:
SELECT h3HexAreaM2(13) AS 面积;
结果:
┌─area─┐
│ 43.9 │
└──────┘
h3HexAreaKm2
返回给定分辨率下六边形的平均面积(平方千米)。
语法
参数
resolution — 索引分辨率。取值范围:[0, 15]。UInt8。
返回值
示例
查询:
SELECT h3HexAreaKm2(13) AS area;
结果:
┌──────area─┐
│ 0.0000439 │
└───────────┘
h3IndexesAreNeighbors
返回给定的 H3 索引是否互为邻居。
语法
h3IndexesAreNeighbors(index1, index2)
参数
返回值
示例
查询:
SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;
结果:
h3ToChildren
返回给定 H3 索引的子索引数组。
语法
h3ToChildren(index, resolution)
参数
index — 六边形索引号。UInt64。
resolution — 索引分辨率。取值范围:[0, 15]。UInt8。
返回值
示例
查询:
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。
返回值
示例
查询:
SELECT h3ToParent(599405990164561919, 3) AS parent;
结果:
┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘
h3ToString
将索引的 H3Index 表示形式转换为字符串形式。
参数
返回值
示例
查询:
SELECT h3ToString(617420388352917503) AS h3_string;
结果:
┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘
stringToH3
将字符串形式转换为 H3Index(UInt64)表示。
语法
参数
index_str — H3 索引的字符串形式。String。
返回值
示例
查询:
SELECT stringToH3('89184926cc3ffff') AS index;
结果:
┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘
h3GetResolution
返回 H3 索引的分辨率。
语法
参数
返回值
示例
查询:
SELECT h3GetResolution(617420388352917503) AS res;
结果:
h3IsResClassIII
返回 H3 索引的分辨率是否为 Class III 朝向。
语法
参数
返回值
1 — 索引的分辨率为 Class III 方向。UInt8。
0 — 索引的分辨率不为 Class III 方向。UInt8。
示例
查询:
SELECT h3IsResClassIII(617420388352917503) AS res;
结果:
h3IsPentagon
返回该 H3 索引是否表示五边形单元格。
语法
参数
返回值
示例
查询:
SELECT h3IsPentagon(644721767722457330) AS pentagon;
结果:
┌─五角形─┐
│ 0 │
└──────────┘
h3GetFaces
返回与给定 H3 索引相交的二十面体的面。
语法
参数
返回值
示例
查询:
SELECT h3GetFaces(599686042433355775) AS faces;
结果:
┌─faces─┐
│ [7] │
└───────┘
h3CellAreaM2
返回与给定 H3 索引对应的单元格的精确面积(单位:平方米)。
语法
参数
返回值
示例
查询:
SELECT h3CellAreaM2(579205133326352383) AS area;
结果:
┌───────────────面积─┐
│ 4106166334463.9233 │
└────────────────────┘
h3CellAreaRads2
返回给定输入 H3 索引所对应单元格的精确面积,单位为平方弧度。
语法
参数
返回值
示例
查询:
SELECT h3CellAreaRads2(579205133326352383) AS area;
结果:
┌────────────────area─┐
│ 0.10116268528089567 │
└─────────────────────┘
h3ToCenterChild
在指定分辨率下,返回给定 H3 索引所包含的中心子(更高分辨率)H3 索引。
语法
h3ToCenterChild(index, resolution)
参数
index — 六边形索引编号。UInt64。
resolution — 索引分辨率。取值范围:[0, 15]。UInt8。
返回值
示例
查询:
SELECT h3ToCenterChild(577023702256844799,1) AS centerToChild;
结果:
┌──────centerToChild─┐
│ 581496515558637567 │
└────────────────────┘
h3ExactEdgeLengthM
返回由输入的 h3 索引表示的单向边的精确边长(单位:米)。
语法
h3ExactEdgeLengthM(index)
参数
返回值
示例
查询:
SELECT h3ExactEdgeLengthM(1310277011704381439) AS exactEdgeLengthM;;
结果:
┌───exactEdgeLengthM─┐
│ 195449.63163407316 │
└────────────────────┘
h3ExactEdgeLengthKm
返回由输入 h3 索引表示的单向边的精确长度,单位为千米。
语法
h3ExactEdgeLengthKm(index)
参数
返回值
示例
查询:
SELECT h3ExactEdgeLengthKm(1310277011704381439) AS exactEdgeLengthKm;;
结果:
┌──exactEdgeLengthKm─┐
│ 195.44963163407317 │
└────────────────────┘
h3ExactEdgeLengthRads
返回输入 h3 索引所表示的有向边的精确长度(以弧度为单位)。
语法
h3ExactEdgeLengthRads(index)
参数
返回值
示例
查询:
SELECT h3ExactEdgeLengthRads(1310277011704381439) AS exactEdgeLengthRads;;
结果:
┌──exactEdgeLengthRads─┐
│ 0.030677980118976447 │
└──────────────────────┘
h3NumHexagons
返回在给定分辨率下的唯一 H3 索引数量。
语法
参数
resolution — 索引分辨率。范围:[0, 15]。UInt8。
返回值
示例
查询:
SELECT h3NumHexagons(3) AS numHexagons;
结果:
┌─numHexagons─┐
│ 41162 │
└─────────────┘
h3PointDistM
返回成对 GeoCoord 点(纬度/经度)之间的“大圆(great circle)”或“haversine”距离,单位为米。
语法
h3PointDistM(lat1, lon1, lat2, lon2)
参数
lat1, lon1 — 点1的纬度和经度(单位:度)。Float64。
lat2, lon2 — 点2的纬度和经度(单位:度)。Float64。
返回值
示例
查询:
SELECT h3PointDistM(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistM;
结果:
┌──────h3PointDistM─┐
│ 2223901.039504589 │
└───────────────────┘
h3PointDistKm
返回 GeoCoord 点对(纬度/经度)之间的大圆(great circle)或半正矢(haversine)距离,单位为千米。
语法
h3PointDistKm(lat1, lon1, lat2, lon2)
参数
lat1, lon1 — 点 1 的纬度和经度(单位:度)。Float64。
lat2, lon2 — 点 2 的纬度和经度(单位:度)。Float64。
返回值
示例
查询:
SELECT h3PointDistKm(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistKm;
结果:
┌─────h3PointDistKm─┐
│ 2223.901039504589 │
└───────────────────┘
h3PointDistRads
返回成对 GeoCoord 点(纬度/经度)之间的“大圆”(great circle)或“半正矢”(haversine)距离,单位为弧度。
语法
h3PointDistRads(lat1, lon1, lat2, lon2)
参数
lat1, lon1 — 点 1 的纬度和经度(单位:度)。Float64。
lat2, lon2 — 点 2 的纬度和经度(单位:度)。Float64。
返回值
示例
查询:
SELECT h3PointDistRads(-10.0 ,0.0, 10.0, 0.0) AS h3PointDistRads;
结果:
┌────h3PointDistRads─┐
│ 0.3490658503988659 │
└────────────────────┘
h3GetRes0Indexes
返回一个数组,包含所有分辨率为 0 的 H3 索引。
语法
返回值
示例
查询:
SELECT h3GetRes0Indexes AS indexes ;
结果:
┌─indexes─────────────────────────────────────┐
│ [576495936675512319,576531121047601151,....]│
└─────────────────────────────────────────────┘
h3GetPentagonIndexes
返回在指定分辨率下的所有五边形 H3 索引。
语法
h3GetPentagonIndexes(resolution)
参数
resolution — 索引分辨率。取值范围:[0, 15]。UInt8。
返回值
示例
查询:
SELECT h3GetPentagonIndexes(3) AS indexes;
结果:
┌─索引────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘
h3Line
返回位于提供的两个索引之间的一系列索引。
语法
参数
返回值
表示连接这两个给定索引的索引路径的 h3 索引数组。Array(UInt64)。
示例
查询:
SELECT h3Line(590080540275638271,590103561300344831) AS indexes;
结果:
┌─indexes────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3Distance
返回以网格单元数表示的两个索引之间的距离。
语法
参数
返回值
如果无法计算距离,则返回负数。
示例
查询:
SELECT h3Distance(590080540275638271,590103561300344831) AS distance;
结果:
┌─距离─┐
│ 7 │
└──────────┘
h3HexRing
返回以提供的原点 h3Index 为中心、半径为 k 的六边形环中各索引。
如果未遇到五边形畸变,则返回 0。
语法
参数
返回值
示例
查询:
SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;
结果:
┌─hexRing─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3GetUnidirectionalEdge
基于给定的起点和终点返回单向边 H3 索引,出错时返回 0。
语法
h3GetUnidirectionalEdge(originIndex, destinationIndex)
参数
originIndex — 起点六边形索引号。UInt64。
destinationIndex — 终点六边形索引号。UInt64。
返回值
示例
查询:
SELECT h3GetUnidirectionalEdge(599686042433355775, 599686043507097599) AS edge;
结果:
┌────────────────edge─┐
│ 1248204388774707199 │
└─────────────────────┘
h3UnidirectionalEdgeIsValid
判断给定的 H3Index 是否为有效的单向边索引。如果是单向边索引则返回 1,否则返回 0。
语法
h3UnidirectionalEdgeisValid(index)
参数
返回值
- 1 — 该 H3 索引是有效的单向边。UInt8。
- 0 — 该 H3 索引不是有效的单向边。UInt8。
示例
查询:
SELECT h3UnidirectionalEdgeIsValid(1248204388774707199) AS validOrNot;
结果:
┌─validOrNot─┐
│ 1 │
└────────────┘
h3GetOriginIndexFromUnidirectionalEdge
从单向边 H3Index 返回起点六边形索引。
语法
h3GetOriginIndexFromUnidirectionalEdge(edge)
参数
返回值
示例
查询:
SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707197) AS origin;
结果:
┌─────────────origin─┐
│ 599686042433355773 │
└────────────────────┘
h3GetDestinationIndexFromUnidirectionalEdge
从单向边 H3Index 获取目标六边形索引。
语法
h3GetDestinationIndexFromUnidirectionalEdge(edge)
参数
返回值
示例
查询:
SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707197) AS destination;
结果:
┌──────────目标──────┐
│ 599686043507097597 │
└────────────────────┘
h3GetIndexesFromUnidirectionalEdge
返回给定单向边 H3Index 的起点和终点六边形索引。
语法
h3GetIndexesFromUnidirectionalEdge(edge)
参数
返回值
由两个值组成的元组 tuple(origin,destination):
如果输入无效,则返回 (0,0)。
示例
查询:
SELECT h3GetIndexesFromUnidirectionalEdge(1248204388774707199) AS indexes;
结果:
┌─indexes─────────────────────────────────┐
│ (599686042433355775,599686043507097599) │
└─────────────────────────────────────────┘
h3GetUnidirectionalEdgesFromHexagon
返回指定 H3Index 的所有单向边。
语法
h3GetUnidirectionalEdgesFromHexagon(index)
参数
返回值
由表示每条单向边的 H3 索引构成的数组。Array(UInt64)。
示例
查询:
SELECT h3GetUnidirectionalEdgesFromHexagon(1248204388774707199) AS edges;
结果:
┌─edges─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [1248204388774707199,1320261982812635135,1392319576850563071,1464377170888491007,1536434764926418943,1608492358964346879] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3GetUnidirectionalEdgeBoundary
返回定义该单向边的坐标。
语法
h3GetUnidirectionalEdgeBoundary(index)
参数
返回值
示例
查询:
SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) AS boundary;
结果:
┌─边界────────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘