Condividi tramite

Funzione h3_kringdistances

  • Articolo

Si applica a: segno di spunta sì Databricks SQL segno di spunta sì Databricks Runtime 11.3 LTS e versioni successive

Restituisce tutte le celle H3 (rappresentate come numeri interi lunghi o stringhe) all'interno della griglia k dalla cella H3 di origine, insieme alla relativa distanza dalla cella H3 di origine.

Sintassi

h3_kringdistances ( h3CellIdExpr, kExpr )

Argomenti

  • h3CellIdExpr: espressione BIGINT o espressione STRING esadecimale che rappresenta un ID cella H3.
  • kExpr: espressione INTEGER che rappresenta la distanza della griglia. kExpr deve essere non negativo.

Valori restituiti

Matrice di struct denominati con due campi, denominati cellid rispettivamente e distance, dove il primo campo nello struct è un ID cella H3 (rappresentato come un numero intero lungo o stringa) e il secondo campo nello struct è la distanza dalla cella H3 di origine (rappresentata come un numero intero). Il tipo per gli ID di cella H3 nell'output è uguale al tipo di h3CellIdExpr.

Gli elementi nell'array restituito vengono ordinati in relazione alla distanza dalla cella H3 di origine. Gli elementi corrispondenti alla stessa distanza nell'array restituito possono essere restituiti in qualsiasi ordine. La funzione restituisce NULL se una delle espressioni di input è NULL. La funzione esegue la convalida parziale relativa al fatto che l'argomento di input sia un ID cella H3 valido. Una condizione necessaria, ma non sufficiente per un ID H3 valido è che il relativo valore è compreso tra 0x08001fffffffffff e 0x08ff3b6db6db6db6. Il comportamento della funzione non è definito se l'ID cella di input non è un ID cella valido. Se il valore della distanza della griglia è zero, la matrice restituita contiene un singolo valore uguale all'ID cella H3 di input.

Condizioni di errore

  • Se h3CellIdExpr è un valore STRING che non può essere convertito in bigint o corrisponde a un valore BIGINT minore o maggiore di 0x08001fffffffffff 0x08ff3b6db6db6db6, la funzione restituisce H3_INVALID_CELL_ID
  • Se kExpr è negativo, la funzione restituisce H3_INVALID_GRID_DISTANCE_VALUE

Esempi

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