H3 インデックス
H3 は、地球の表面を同じ大きさの六角形セルのグリッドに分割する地理空間インデックスシステムです。このシステムは階層構造になっており、最上位レベルの各六角形 (「親」) は、同じ形状でより小さい 7 個の六角形 (「子」) に分割され、その先も同様に続きます。
この階層のレベルは resolution と呼ばれ、0 から 15 までの値を取ります。0 は最も大きく粗いセルを持つ base レベルです。
緯度と経度のペアは、グリッドセルを識別する 64 ビットの H3 インデックスに変換できます。
H3 インデックスは主に、位置情報のバケット分けやその他の地理空間処理に使用されます。
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
指定された H3 インデックスの境界を表す (lat, lon) のペアからなる配列を返します。
構文
引数
戻り値
例
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;
┌─area─┐
│ 43.9 │
└──────┘
h3HexAreaKm2
指定した解像度における六角形の平均面積を平方キロメートル単位で返します。
構文
パラメーター
resolution — インデックスの解像度。範囲: [0, 15]。UInt8。
戻り値
例
SELECT h3HexAreaKm2(13) AS area;
┌──────area─┐
│ 0.0000439 │
└───────────┘
h3IndexesAreNeighbors
指定された H3 インデックス同士が隣接しているかどうかを返します。
構文
h3IndexesAreNeighbors(index1, index2)
引数
戻り値
1 — インデックスが隣接している。UInt8。0 — インデックスが隣接していない。UInt8。
例
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。
戻り値
- 六角形インデックス番号。エラー時には 0 を返します。UInt64。
例
SELECT stringToH3('89184926cc3ffff') AS index;
┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘
h3GetResolution
H3 インデックスの解像度を返します。
構文
パラメーター
返される値
- インデックスの解像度。範囲：
[0, 15]。UInt8。
例
SELECT h3GetResolution(617420388352917503) AS res;
h3IsResClassIII
H3 インデックスの解像度が Class III の向きにあるかどうかを返します。
構文
パラメーター
戻り値
1 — インデックスの解像度は Class III 向きです。UInt8。0 — インデックスの解像度は Class III 向きではありません。UInt8。
例
SELECT h3IsResClassIII(617420388352917503) AS res;
h3IsPentagon
この H3 インデックスが五角形のセルを表しているかどうかを返します。
構文
パラメータ
戻り値
1 — インデックスが五角形セルを表す。UInt80 — インデックスが五角形セルを表さない。UInt8
例
SELECT h3IsPentagon(644721767722457330) AS pentagon;
┌─pentagon─┐
│ 0 │
└──────────┘
h3GetFaces
指定された H3 インデックスと交差する正二十面体の面を返します。
構文
パラメーター
戻り値
例
SELECT h3GetFaces(599686042433355775) AS faces;
┌─faces─┐
│ [7] │
└───────┘
h3CellAreaM2
指定された H3 インデックスに対応するセルの正確な面積を、平方メートル単位で返します。
構文
パラメータ
戻り値
例
SELECT h3CellAreaM2(579205133326352383) AS area;
┌───────────────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。
返される値
- 指定された解像度において、与えられた H3 インデックスに含まれる中心の子の H3 インデックス。UInt64。
例
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 インデックスの数を返します。
構文
h3NumHexagons(resolution)
パラメーター
resolution — インデックスの解像度。範囲: [0, 15]。 UInt8。
戻り値
例
SELECT h3NumHexagons(3) AS numHexagons;
┌─numHexagons─┐
│ 41162 │
└─────────────┘
h3PointDistM
GeoCoord の点 (緯度/経度) ペア間の「大円」または「ハバーサイン」距離をメートル単位で返します。
構文
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 ポイント (緯度/経度) ペア間の「大円」または「ハバーサイン (haversine) 」距離をキロメートル単位で返します。
構文
h3PointDistKm(lat1, lon1, lat2, lon2)
引数
lat1, lon1 — 点1 の緯度および経度 (度単位) 。Float64。lat2, lon2 — 点2 の緯度および経度 (度単位) 。Float64。
戻り値
- Haversine または大円距離 (キロメートル単位) 。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 — 点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;
┌─indexes────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘
h3Line
指定された 2 つのインデックス間にあるインデックスの列を返します。
構文
パラメーター
start — 開始点を表す六角形インデックス番号。UInt64。end — 終了点を表す六角形インデックス番号。UInt64。
戻り値
指定された 2 つのインデックス間の経路を表す H3 インデックスの配列。Array(UInt64)。
例
SELECT h3Line(590080540275638271,590103561300344831) AS indexes;
┌─indexes────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3Distance
指定された 2 つのインデックス間の距離を、グリッドセル単位で返します。
構文
パラメーター
start — 開始点を表す六角形インデックス番号。UInt64。end — 終了点を表す六角形インデックス番号。UInt64。
返される値
距離の算出に失敗した場合は負の数を返します。
例
SELECT h3Distance(590080540275638271,590103561300344831) AS distance;
┌─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)
パラメーター
edge — 単方向エッジを表す六角形インデックス番号。UInt64。
戻り値
例
SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707197) AS origin;
┌─────────────origin─┐
│ 599686042433355773 │
└────────────────────┘
h3GetDestinationIndexFromUnidirectionalEdge
単方向エッジを表す H3Index から、終点の六角形インデックスを返します。
構文
h3GetDestinationIndexFromUnidirectionalEdge(edge)
パラメーター
edge — 単方向エッジを表す六角形インデックス番号。UInt64。
戻り値
例
SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707197) AS destination;
┌────────destination─┐
│ 599686043507097597 │
└────────────────────┘
h3GetIndexesFromUnidirectionalEdge
指定された単方向エッジ H3Index から、起点と終点の六角形インデックスを返します。
構文
h3GetIndexesFromUnidirectionalEdge(edge)
パラメーター
edge — 単方向エッジを表す六角形インデックス番号。UInt64。
返される値
tuple(origin,destination) という 2 つの値からなるタプルを返します。
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。
返される値
例
SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) AS boundary;
┌─boundary────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘
