Udostępnij za pośrednictwem

Funkcja h3_distance

  • Artykuł

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

Zwraca odległość siatki dwóch wejściowych identyfikatorów komórek H3.

Składnia

h3_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 powinny mieć taką samą rozdzielczość.

Funkcja zwraca wartość NULL, jeśli dowolne z wyrażeń wejściowych ma wartość NULL. Funkcja wykonuje częściową walidację dotyczącą tego, czy argument wejściowy jest prawidłowym identyfikatorem komórki 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ż 0x08001fffffffffff 0x08ff3b6db6db6db6, funkcja zwraca H3_INVALID_CELL_ID.
  • Jeśli odległość siatki jest niezdefiniowana, funkcja zwraca H3_UNDEFINED_GRID_DISTANCE. Odległość siatki może być niezdefiniowana z dowolnego z następujących powodów:
    • Dwie wejściowe komórki H3 mają inną rozdzielczość.
    • 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))
  [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