Freigeben über

h3_try_distance-Funktion

  • Artikel

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

Diese Funktion verhält sich ähnlich wie h3_distance, mit der Ausnahme, dass NULL anstelle eines Fehlers zurückgegeben wird, wenn der Rasterabstand zwischen den beiden H3-Zell-IDs der Eingabe derselben Auflösung nicht definiert ist. Insbesondere gibt sie den Rasterabstand der beiden H3-Zell-IDs der Eingabe zurück, die von derselben Auflösung erwartet werden, oder NULL, wenn der Abstand nicht definiert ist.

Syntax

h3_try_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, oder NULL, wenn der Abstand nicht definiert ist.

Die Funktion gibt „NULL“ zurück, wenn einer der Eingabeausdrücke „NULL“ ist. Sie überprüft teilweise die Eingabeargumente, um festzustellen, ob sie gültige H3-Zell-IDs darstellen. 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 die beiden H3-Eingabezellen eine unterschiedliche Auflösung aufweisen, gibt die Funktion H3_UNDEFINED_GRID_DISTANCE zurück.
  • Wenn der Rasterabstand zwischen zwei H3-Zellen derselben Auflösung nicht definiert ist, gibt die Funktion NULL zurück. Der Rasterabstand kann aus einem der folgenden Gründe undefiniert sein:
    • 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))
 NULL

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

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
 NULL