h3_distance-Funktion

  • Artikel

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

Gibt den Rasterabstand der beiden eingegebenen H3-Zellen-IDs zurück.

Syntax

h3_distance ( h3CellId1Expr, h3CellId2Expr )

Argumente

  • h3CellId1Expr: Ein BIGINT-Ausdruck oder ein hexadezimaler STRING-Ausdruck, der eine H3-Zellen-ID darstellt.
  • h3CellId2Expr: Ein BIGINT-Ausdruck oder ein hexadezimaler STRING-Ausdruck, der eine H3-Zellen-ID darstellt.

Gibt zurück

Ein BIGINT-Wert, der der Rasterabstand der beiden eingegebenen H3-Zellen ist, von denen erwartet wird, dass sie dieselbe Auflösung haben.

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 eine der beiden Eingabezellen-IDs keine gültige Zellen-ID ist.

Fehlerbedingungen

  • Wenn h3CellId1Expr oder h3CellId2Expr 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 der Rasterabstand nicht definiert ist, gibt die Funktion H3_UNDEFINED_GRID_DISTANCE zurück. Der Rasterabstand kann aus einem der folgenden Gründe undefiniert sein:
    • Die zwei Eingabe-H3-Zellen haben eine unterschiedliche Auflösung.
    • Jede der zwei eingegebenen H3-Zellen ist eine fünfeckige Zelle.
    • Die beiden H3-Zellen sind durch eine fünfeckige Zelle getrennt.
    • Die beiden H3-Zellen sind zu weit voneinander entfernt.

Beispiele

-- Example where the two arguments are BIGINTs representing H3 cells.
> SELECT h3_distance(599686030622195711, 599686015589810175);
 2

-- Example where the two arguments are hexadecimal STRINGs representing H3 cells.
> SELECT h3_distance('85283447fffffff', '8528340ffffffff')
 2

-- Example of two cells that too far apart from each other.
> SELECT h3_distance(h3_longlatash3(-120, 45, 13), h3_longlatash3(120, 45, 13))
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 635723017894513407 and 635869868887430591 is undefined

-- Example of two cells with different resolutions.
> SELECT h3_distance(h3_longlatash3(120, 45, 13), h3_longlatash3(120, 45, 12));
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 635869868887430591 and 631366269260060159 is undefined

-- First cell ID is a pentagon.
> SELECT h3_distance(590112357393367039, 590678880759578623)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112357393367039 and 590678880759578623 is undefined

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112494832320511 and 590112632271273983 is undefined