h3_kringdistances-Funktion

  • Artikel

Gilt für: Häkchen ja Databricks SQL Häkchen gesetzt ja Databricks Runtime 11.3 LTS und höher

Gibt alle H3-Zellen (dargestellt als lange Ganzzahlen oder Zeichenfolgen) innerhalb des Rasterabstands k von der ursprünglichen H3-Zelle zusammen mit ihrer Entfernung von der ursprünglichen H3-Zelle zurück.

Syntax

h3_kringdistances ( h3CellIdExpr, kExpr )

Argumente

  • h3CellIdExpr: Ein BIGINT-Ausdruck oder ein hexadezimaler STRING-Ausdruck, der eine H3-Zellen-ID darstellt.
  • kExpr: Ein INTEGER-Ausdruck, der den Rasterabstand darstellt. kExpr darf nicht negativ sein.

Gibt zurück

Ein ARRAY aus benannten Strukturen mit zwei Feldern namens cellid bzw. distance, wobei das erste Feld in der Struktur eine H3-Zellen-ID (dargestellt als lange Ganzzahl oder Zeichenfolge) und das zweite Feld in der Struktur die Entfernung vom Ursprung ist H3-Zelle (als Ganzzahl dargestellt). Der Typ für die H3-Zellen-IDs in der Ausgabe ist derselbe wie der Typ von h3CellIdExpr.

Die Elemente im zurückgegebenen ARRAY werden in Bezug auf ihre Entfernung von der ursprünglichen H3-Zelle sortiert. Die Elemente, die dem gleichen Abstand im zurückgegebenen ARRAY entsprechen, können in beliebiger Reihenfolge zurückgegeben werden. Die Funktion gibt NULL zurück, wenn einer der Eingabeausdrücke NULL ist. Die Funktion überprüft teilweise, ob das Eingabeargument eine gültige H3-Zellen-ID ist. Eine notwendige, aber nicht hinreichende Bedingung für eine gültige H3-ID ist, dass ihr Wert zwischen 0x08001fffffffffff und 0x08ff3b6db6db6db6 liegt. Das Verhalten der Funktion ist undefiniert, wenn die Eingabezellen-ID keine gültige Zellen-ID ist. Wenn der Wert des Rasterabstands null ist, enthält das zurückgegebene Array einen einzelnen Wert, der der Eingabe-H3-Zellen-ID entspricht.

Fehlerbedingungen

  • Wenn h3CellIdExpr ein STRING ist, der nicht in BIGINT konvertiert werden kann oder einem BIGINT-Wert entspricht, der kleiner als 0x08001fffffffffff oder größer als 0x08ff3b6db6db6db6 ist, gibt die Funktion H3_INVALID_CELL_ID zurück
  • Wenn kExpr negativ ist, gibt die Funktion H3_INVALID_GRID_DISTANCE_VALUE zurück

Beispiele

-- 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