h3_tessellateaswkb 関数

  • [アーティクル]

適用対象: check marked yes Databricks SQL Databricks Runtime 14.2 以上

指定した解像度の H3 セルを使って、入力した地理的な場所のテセレーションを返します。 テッセレーションは構造体の ARRAY で表され、それぞれがテセレーションの要素を表します。 テッセレーションの各要素は、H3 セル ID (長整数で表されます)、入力地理情報がセルを完全にカバーするかどうかを示すブール値、および入力地理情報と H3 セルの交差に関する WKB 記述に対応する BINARY 値で構成されます。

返された H3 セルは、指定された解像度で、入力地理情報を完全にカバーする最小限の六角形または五角形のセットを形成します。 WKB 表現で返される地理情報は、入力地理情報のテッセレーションを形成します。

構文

h3_tessellateaswkb ( geographyExpr, resolutionExpr )

引数

  • geographyExpr: WKB、WKT、または GeoJSON の地理的な場所を表す BINARY または STRING 式。 地理的な場所には、WGS84 座標参照系を参照する経度と緯度の座標が必要です。
  • resolutionExpr: 値が 0 と 15 の間の INT 式。H3 セル ID の解像度を指定します。

返品

BIGINT、BOOLEAN、BINARY 型の 3 つのフィールド (それぞれ cellid、core、chip という名前) を持つ名前付き構造体の ARRAY。H3 セルとともに入力地理情報のテッセレーションを指定した解像度で表します。

構造体の最初のフィールドは、H3 セル ID (長整数として表されます) です。 構造体の 2 番目のフィールドは、H3 セルがコア セルであるかどうかを示すブール値です。コア セルの場合、フィールドの値は true になります。コア セルではない場合は、フィールドの値は false です。 コア セルは、入力地理情報で完全にカバーされる H3 セルです (つまり、入力地理情報との交差はセル自体です)。 3 番目のフィールドは、入力地理情報と H3 セルの交差部分となる地理情報の WKB 記述を表す BINARY 値です。 返された H3 セルは、入力地理情報を最小限にカバーする部分をまとめて形成します。 返された WKB 記述に対応する地理情報は、入力地理情報のテッセレーション (分解) をまとめて形成します。

入力式のいずれかが NULL の場合、この関数は NULL を返します。 最初の入力引数が BINARY 型の場合、入力値は、ポイント、ラインストリング、ポリゴン、マルチストリング、マルチポリゴンの WKB 記述であることが期待されます。 最初の入力引数が STRING 型の場合、入力値は、WKT、またはポイント、ラインストリング、ポリゴン、マルチストリング、マルチポリゴンの GeoJSON 記述であることが期待されます。 入力地理情報のディメンションは、2D、3DZ、3DM、または 4D にすることができます。

エラー条件

  • geographyExpr が BINARY 型で、値が無効な WKB であるか、ジオメトリ コレクションを表している場合、関数は WKB_PARSE_ERROR を返します。
  • geographyExpr が STRING 型で、値が無効な WKT であるか、ジオメトリ コレクションを表している場合、関数は WKT_PARSE_ERROR を返します。
  • geographyExpr が STRING 型で、値が無効な GeoJSON であるか、ジオメトリ コレクションを表している場合、関数は GEOJSON_PARSE_ERROR を返します。
  • resolutionExpr が 0 より小さいか 15 より大きい場合、関数は H3_INVALID_RESOLUTION_VALUE を返します。

例

> SELECT h3_h3tostring(cellid), core, hex(chip) FROM (SELECT inline(h3_tessellateaswkb('MULTIPOINT(20 0,20 10,40 30)', 0))) ORDER BY 1
  802dfffffffffff     false 010100000000000000000044400000000000003E40
  806bfffffffffff     false 010400000002000000010100000000000000000034400000000000000000010100000000000000000034400000000000002440

-- Feeding an empty geometry collection in GeoJSON format (geometry collections are not supported).
> SELECT h3_tessellateaswkb('{"type":"GeometryCollection","geometries":[]}', 2)
  [GEOJSON_PARSE_ERROR] Error parsing GeoJSON: Invalid or unsupported type '"GeometryCollection"' at position 9 SQLSTATE: 22023

-- Feeding an invalid WKB (invalid endianness value)
> SELECT h3_tessellateaswkb(unhex('020700000000'), 2)
  [WKB_PARSE_ERROR] Error parsing WKB: Invalid byte order 2 at position 1 SQLSTATE: 22023

-- Feeding an invalid polygon in WKT (polygon is not closed)
> SELECT h3_tessellateaswkb('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-74.0060 40.7128))', 2)
  [WKT_PARSE_ERROR] Error parsing WKT: Found non-closed ring at position 80 SQLSTATE: 22023

-- Resolution is out of range.
> SELECT h3_tessellateaswkb('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-122.4194 37.7749))', 16)
  [H3_INVALID_RESOLUTION_VALUE] H3 resolution 16 must be between 0 and 15, inclusive SQLSTATE: 22023