Udostępnij za pośrednictwem

Funkcja h3_hexring

  • Artykuł

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

Zwraca tablicę komórek H3 tworzących pusty pierścień sześciokątny wyśrodkowany w komórce H3 pochodzenia i znajdujących się w odległości k siatki od komórki początkowej H3.

Składnia

h3_hexring ( 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 wartości tego samego typu co typ h3CellIdExpr wyrażenia, odpowiadający identyfikatorom komórek H3, które mają taką samą rozdzielczość jak komórka wejściowa H3 i które tworzą pusty pierścień wyśrodkowany w komórce początkowej H3 w odległości k, gdzie k jest wartością kExpr.

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, która jest mniejsza lub większa niż 0x08001fffffffffff 0x08ff3b6db6db6db6, funkcja zwraca H3_INVALID_CELL_ID.
  • Jeśli kExpr jest ujemna, funkcja zwraca H3_INVALID_GRID_DISTANCE_VALUE.
  • Jeśli istnieje pentagon w dowolnym miejscu w k-ringu komórki pochodzenia, funkcja zwraca H3_PENTAGON_ENCOUNTERED_ERROR.

Przykłady

-- Simple example where the first argument is a BIGINT.
> SELECT h3_hexring(599686042433355775, 1)
  [599686014516068351,599686030622195711,599686044580839423,599686038138388479,599686043507097599,599686015589810175]

-- Simple example where the first argument is a STRING.
> SELECT h3_hexring('85283473fffffff', 1)
  [8528340bfffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff]

-- First input is an invalid H3 cell ID.
> SELECT h3_hexring(0, 0)
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID

-- Second input is an invalid grid distance value.
> SELECT h3_hexring('85283473fffffff', -1)
  [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative

-- The input cell is a hexagonal cell adjacent to a pentagonal cell (the 2-ring of the hexagonal cell contains the pentagon).
> SELECT H3_HexRing('8007fffffffffff', 2)
  [H3_PENTAGON_ENCOUNTERED_ERROR] A pentagon was encountered while computing the hex ring of '8007fffffffffff' with grid distance 2