DatabricksのH3地理空間関数

H3 geospatial functions | Databricks on AWS [2023/11/9時点]の翻訳です。

本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。

適応対象 Databricks SQL, Databricksランタイム

H3はグローバルグリッドインデクシングシステムです。グリッドシステムでは表面、この場合には地球の表面に正確に一致するように、長方形や三角形のような形状を使用します。H3システムは六角形(そして一部で五角形)を使用するように設計されており、その階層構造で16レベルの解像度を提供しています。解像度が高くなるほど、一致させる形状は小さくなります。

H3エクスプレッションはPhoton有効化クラスターかDatabricks SQL proあるいはサーバレスのDatabricks SQLウェアハウスでのみサポートされています。

H3の解像度やH3の起源についてはドキュメントを参照ください。

以下も参照ください:

• H3 Quickstart (Databricks SQL)
• H3 geospatial functions example
• Alphabetical list of H3 geospatial functions

地理空間分析のためのH3

H3では空間情報の処理、分析における一般的なパターンをサポートしています。標準フォーマット(緯度軽度、Well-known text (WKT)、Well-known binary (WKB))やGeoJSONからH3セルIDへの地理空間データのインデックス作成からスタートします。単一のデータセットにおいて、位置に関する質問に答えるためにセルIDで集計を行うことができます。インデックスが作成された複数のデータセットにおいて、セルIDを用いてそれらを結合し、それぞれのデータセットがどのように関係しているのかを明らかにすることができます。このデータセットの結合は意味論的には空間joinですが、空間述語を必要としません。

DatabricksでH3を使うことのメリットは？

お使いのH3でインデクシングされたデータに対する効率的な格納やレイアウトのためにDelta Lakeの機能を活用できます。Delta Lakeの(H3セルIDに対する)Z-orderingによるOPTIMIZEオペレーションによって、データを空間的に近い場所に配置することができます。さらに、Delta Lakeのデータスキッピングアルゴリズムは、読み込む必要のあるデータのボリュームをインテリジェントに削減するために、この局所性を活用します。

データをどのように操作するのかついての柔軟性を手に入れることができます。Big Integerあるいは文字列として格納されたH3セルIDを操作することを選択することができます。H3セルIDを用いて最高のパフォーマンスを手に入れるには、Big Integer表現を使いましょう。H3エクスプレッションの詳細な使い方に関しては、SQL reference guideをご覧ください。

注意
H3ライブラリをインストールする必要はありません。Databricksランタイム11.2以降では、バージョン3.7.0のH3 JavaライブラリがDatabricksランタイムに含まれています。

H3にアクセスするためのDatabricks関数のインポート(Databricksランタイム)

Databricks SQLやSpark SQLではインポートは不要です。

ノートブックでPythonやScalaのH3関数をインポートするには以下のコマンドを実行します。

Python

from pyspark.databricks.sql import functions as dbf

Scala

import com.databricks.sql.functions._

H3地理空間関数のリスト(Databricks SQL)

インポート

関数	説明
h3_coverash3(geographyExpr, resolutionExpr)	入力された線形、領域ジオグラフィを完全にカバーし、指定された解像度の六角形、五角形の最小セットに対応するH3セルID(BIGINT表現)のARRAYを返却します。
h3_coverash3string(geographyExpr, resolutionExpr)	入力された線形、領域ジオグラフィを完全にカバーし、指定された解像度の六角形、五角形の最小セットに対応するH3セルID(文字列表現)のARRAYを返却します。
h3_longlatash3(longitudeExpr, latitudeExpr, resolutionExpr)	指定された解像度での緯度経度に対応するH3セルID(BIGINT)を返却します。
h3_longlatash3string(longitudeExpr, latitudeExpr, resolutionExpr)	指定された解像度での緯度経度に対応するH3セルID(16進数文字列)を返却します。
h3_pointash3(geographyExpr, resolutionExpr)	指定された解像度でのポイントに対応するH3セルID(BIGINT)を返却します。
h3_pointash3string(geographyExpr, resolutionExpr)	指定された解像度でのポイントに対応するH3セルID(文字列)を返却します。
h3_polyfillash3(geographyExpr, resolutionExpr)	入力領域ジオグラフィに包含される、指定された解像度の六角形、五角形に対応するH3セルID(BIGINT)のARRAYを返却します。
h3_polyfillash3string(geographyExpr, resolutionExpr)	入力領域ジオグラフィに包含される、指定された解像度の六角形、五角形に対応するH3セルID(文字列)のARRAYを返却します。
h3_try_polyfillash3(geographyExpr, resolutionExpr)	入力領域ジオグラフィに包含される、指定された解像度の六角形、五角形に対応するH3セルID(BIGINT)のARRAYを返却します。
h3_try_polyfillash3string(geographyExpr, resolutionExpr)	入力領域ジオグラフィに包含される、指定された解像度の六角形、五角形に対応するH3セルID(文字列)のARRAYを返却します。

エクスポート

関数	説明
h3_boundaryasgeojson(h3CellIdExpr)	入力H3セルのポリゴンの境界をGeoJSONフォーマットで返却します。
h3_boundaryaswkb(h3CellIdExpr)	入力H3セルのポリゴンの境界をWKBフォーマットで返却します。
h3_boundaryaswkt(h3CellIdExpr)	入力H3セルのポリゴンの境界をWKTフォーマットで返却します。
h3_centerasgeojson(h3CellIdExpr)	入力H3セルのポリゴンの中心をポイントとしてGeoJSONフォーマットで返却します。
h3_centeraswkb(h3CellIdExpr)	入力H3セルのポリゴンの中心をポイントとしてWKBフォーマットで返却します。
h3_centeraswkt(h3CellIdExpr)	入力H3セルのポリゴンの中心をポイントとしてWKTフォーマットで返却します。

変換

関数	説明
h3_h3tostring(h3CellIdExpr)	入力のH3セルIDを等価の16進数文字列表現に変換します。
h3_stringtoh3(h3CellIdStringExpr)	H3セルIDの16進数文字列表現であることが期待される入力文字列をH3セルIDのBIGINT表現に変換します。

述語

関数	説明
h3_ischildof(h3CellId1Expr, h3CellId2Expr)	最初のH3セルIDが2番目のH3セルIDと同じあるいは子供関係である場合にtrueを返却します。
h3_ispentagon(h3CellIdExpr)	入力のBIGINTあるいは16進数文字列が五角形セルである場合にtrueを返却します。

検証

関数	説明
h3_isvalid(expr)	入力BIGINT、文字列が適切なH3セルIDの場合trueを返却します。
h3_try_validate(h3CellIdExpr)	入力BIGINT、文字列が適切なH3セルIDの場合trueを返却します。そうでない場合にはNULLを返却します。
h3_validate(h3CellIdExpr)	入力BIGINT、文字列が適切なH3セルIDの場合、入力値を返却します。そうでない場合にはエラーになります。

距離関係

関数	説明
h3_distance(h3CellId1Expr, h3CellId2Expr)	2つの入力H3セルIDのグリッド距離を返却します。
h3_hexring(h3CellIdExpr, kExpr)	オリジンのH3セルを中心とし、オリジンH3セルからkのグリッド距離を持つ空洞六角形リングを形成するH3セルIDの配列を返却します。
h3_kring(h3CellIdExpr, kExpr)	オリジンのセルIDからkの(グリッド)距離に含まれるH3セルIDを返却します。
h3_kringdistances(h3CellIdExpr, kExpr)	オリジンのH3セルからkのグリッド距離に含まれるすべてのH3セルのID(LONG INTあるいは文字列表現)と、オリジンセルからの距離を返却します。
h3_try_distance(h3CellId1Expr, h3CellId2Expr)	同じ解像度の二つの入力H3セルIDのグリッド距離を返却します。距離が不定の場合、NULLを返却します。

トラバース

関数	説明
h3_maxchild(h3CellIdExpr, resolutionExpr)	指定された解像度における入力H3セルの最大値を持つ子供を返却します。
h3_minchild(h3CellIdExpr, resolutionExpr)	指定された解像度における入力H3セルの最小値を持つ子供を返却します。
h3_resolution(h3CellIdExpr)	入力H3セルIDの解像度を返却します。
h3_tochildren(h3CellIdExpr, resolutionExpr)	入力H3セルIDの指定された解像度における子供のH3セルIDの配列を返却します。
h3_toparent(h3CellIdExpr, resolutionExpr)	入力H3セルIDの指定された解像度における親H3セルIDを返却します。

圧縮

関数	説明
h3_compact(h3CellIdsExpr)	入力されたH3セルIDのセットを可能な限りコンパクトにします。
h3_uncompact(h3CellIdsExpr, resolutionExpr)	指定された解像度で入力されたH3セルIDのコンパクトな状態を解除します。

はじめてのDatabricks

はじめてのDatabricks

Databricks無料トライアル

Databricks無料トライアル