次の方法で共有

h3_kringdistances 関数

  • [アーティクル]

適用対象: check marked yes Databricks SQL Databricks Runtime 11.3 LTS 以降

起点 H3 セルからグリッド距離 k 以内にあるすべての H3 セル (長整数または文字列として表されます) と、起点 H3 セルからの距離を返します。

構文

h3_kringdistances ( h3CellIdExpr, kExpr )

引数

  • h3CellIdExpr: H3 セル ID を表す BIGINT 式または 16 進数の STRING 式。
  • kExpr: グリッド距離を表す INTEGER 式。 kExpr は負以外でなければなりません。

戻り値

cellid と distance という 2 つのフィールドを持つ名前付き構造体の ARRAY で、構造体の最初のフィールドは H3 セル ID (長整数または文字列として表されます)、構造体の 2 番目のフィールドは起点 H3 セルからの距離 (整数として表されます) です。 出力される H3 セル ID の種類は h3CellIdExpr の種類と同じです。

返された ARRAY の要素は、起点 H3 セルからの距離を基準として並べ替えられます。 返される ARRAY の中で同じ距離に対応する要素は、任意の順序で返される可能性があります。 いずれかの入力式が NULL の場合、この関数は NULL を返します。 この関数は、入力引数が有効な H3 セル ID であるかどうかに関する部分的な検証を行います。 有効な H3 ID の必要条件 (ただし、十分条件ではない) は、その値が 0x08001fffffffffff と 0x08ff3b6db6db6db6 の間にあることです。 入力セル ID が有効なセル ID でない場合、関数の動作は未定義です。 グリッド距離の値が 0 の場合、返される配列には入力 H3 セル ID と等しい 1 つの値が含まれます。

エラー条件

  • h3CellIdExpr が、BIGINT に変換できない、または 0x08001fffffffffff より小さいか 0x08ff3b6db6db6db6 より大きい BIGINT 値に対応する STRING の場合、関数は H3_INVALID_CELL_ID を返します
  • kExpr が負の場合、関数は H3_INVALID_GRID_DISTANCE_VALUE を返します

例

-- Simple example where the first argument is a BIGINT.
> SELECT h3_kringdistances(599686042433355775, 1)
  [{"cellid":599686042433355775,"distance":0},{"cellid":599686030622195711,"distance":1},{"cellid":599686044580839423,"distance":1},{"cellid":599686038138388479,"distance":1},{"cellid":599686043507097599,"distance":1},{"cellid":599686015589810175,"distance":1},{"cellid":599686014516068351,"distance":1}]

-- Simple example where the first argument is a STRING.
> SELECT h3_kringdistances('85283473fffffff', 1)
  [{"cellid":"85283473fffffff","distance":0},{"cellid":"85283447fffffff","distance":1},{"cellid":"8528347bfffffff","distance":1},{"cellid":"85283463fffffff","distance":1},{"cellid":"85283477fffffff","distance":1},{"cellid":"8528340ffffffff","distance":1},{"cellid":"8528340bfffffff","distance":1}]

-- First input is an invalid H3 cell ID.
> SELECT h3_kringdistances(0, 0)
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID

-- Second input is an invalid grid distance value.
> SELECT h3_kringdistances('85283473fffffff', -1)
  [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative