Udostępnij za pośrednictwem

Funkcja h3_kringdistances

  • Artykuł

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

Zwraca wszystkie komórki H3 (reprezentowane jako długie liczby całkowite lub ciągi) w odległości siatki od komórki początkowej H3 wraz z ich odległością k od komórki początkowej H3.

Składnia

h3_kringdistances ( h3CellIdExpr, kExpr )

Argumenty

  • h3CellIdExpr: wyrażenie BIGINT lub wyrażenie szesnastkowe STRING reprezentujące identyfikator komórki H3.
  • kExpr: Wyrażenie INTEGER reprezentujące odległość siatki. kExpr musi być nieujemna.

Zwraca

Tablica nazwanych struktur z dwoma polami o nazwach cellid i distance, odpowiednio, gdzie pierwsze pole w strukturę jest identyfikatorem komórki H3 (reprezentowanym jako długa liczba całkowita lub ciąg), a drugie pole w strukturę jest jego odległość od komórki początkowej H3 (reprezentowanej jako liczba całkowita). Typ identyfikatorów komórek H3 w danych wyjściowych jest taki sam jak typ h3CellIdExpr.

Elementy w zwracanej tablicy są sortowane w odniesieniu do ich odległości od komórki początkowej H3. Elementy odpowiadające tej samej odległości w zwróconej tablicy mogą być zwracane w dowolnej kolejności. 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 identyfikator komórki wejściowej nie jest prawidłowym identyfikatorem komórki. Jeśli wartość odległości siatki wynosi zero, zwracana tablica zawiera pojedynczą wartość równą wejściowemu identyfikatorowi komórki H3.

Warunki błędu

  • Jeśli h3CellIdExpr 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 kExpr jest ujemna, funkcja zwraca H3_INVALID_GRID_DISTANCE_VALUE

Przykłady

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