Funkcja h3_try_distance

  • Artykuł

Dotyczy:zaznacz pole wyboru oznaczone jako tak Databricks SQL zaznacz pole wyboru oznaczone jako tak Databricks Runtime 13.3 LTS i nowsze

Ta funkcja zachowuje się podobnie do h3_distance, z tą różnicą, że wartość NULL jest zwracana zamiast błędu, jeśli odległość siatki między dwoma wejściowymi identyfikatorami komórek H3 tej samej rozdzielczości jest niezdefiniowana. W szczególności zwraca odległość siatki dwóch wejściowych identyfikatorów komórek H3, które powinny być tego samego rozdzielczości lub null, jeśli odległość jest niezdefiniowana.

Składnia

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argumenty

  • h3CellId1Expr: wyrażenie BIGINT lub wyrażenie szesnastkowe STRING reprezentujące identyfikator komórki H3.
  • h3CellId2Expr: wyrażenie BIGINT lub wyrażenie szesnastkowe STRING reprezentujące identyfikator komórki H3.

Zwraca

Wartość BIGINT, która jest odległością siatki dwóch wejściowych komórek H3, które mają taką samą rozdzielczość, lub NULL, jeśli odległość jest niezdefiniowana.

Funkcja zwraca wartość NULL, jeśli dowolne z wyrażeń wejściowych ma wartość NULL. Częściowo weryfikuje argumenty wejściowe, aby określić, czy reprezentują prawidłowe identyfikatory komórek H3. Wymagany, ale nie wystarczający warunek prawidłowego identyfikatora H3 jest taki, że jego wartość mieści się między 0x08001fffffffffff i 0x08ff3b6db6db6db6. Zachowanie funkcji jest niezdefiniowane, jeśli którykolwiek z dwóch identyfikatorów komórek wejściowych nie jest prawidłowym identyfikatorem komórki.

Warunki błędu

  • Jeśli h3CellId1Expr lub h3CellId2Expr jest ciągiem, którego nie można przekonwertować na BIGINT lub odpowiada wartości BIGINT mniejszej lub większej niż 0x08001fffffffffff0x08ff3b6db6db6db6, funkcja zwraca H3_INVALID_CELL_ID.
  • Jeśli dwie wejściowe komórki H3 mają inną rozdzielczość, funkcja zwraca H3_UNDEFINED_GRID_DISTANCE.
  • Jeśli odległość siatki między dwoma komórkami H3 tej samej rozdzielczości jest niezdefiniowana, funkcja zwraca wartość NULL. Odległość siatki może być niezdefiniowana z dowolnego z następujących powodów:
    • Każda z dwóch wejściowych komórek H3 jest komórką pentagonalną.
    • Dwie komórki H3 są oddzielone komórką pentagonu.
    • Dwie komórki H3 są zbyt odległe od siebie.

Przykłady

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