Funzione h3_try_distance

Si applica a: Databricks SQL Databricks Runtime 13.3 LTS e versioni successive

Questa funzione si comporta in modo analogo a h3_distance, ad eccezione del fatto che viene restituito NULL anziché un errore se la distanza della griglia tra i due ID di cella H3 di input della stessa risoluzione non è definita. In particolare, restituisce la distanza della griglia dei due ID di cella H3 di input, che devono essere della stessa risoluzione o NULL se la distanza non è definita.

Sintassi

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argomenti

• h3CellId1Expr: espressione BIGINT o espressione STRING esadecimale che rappresenta un ID cella H3.
• h3CellId2Expr: espressione BIGINT o espressione STRING esadecimale che rappresenta un ID cella H3.

Valori restituiti

Valore BIGINT che corrisponde alla distanza della griglia delle due celle H3 di input, che dovrebbero avere la stessa risoluzione o NULL se la distanza non è definita.

La funzione restituisce NULL se una qualsiasi delle espressioni di input è NULL. Convalida parzialmente gli argomenti di input per determinare se rappresentano ID di cella H3 validi. 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 uno dei due ID cella di input non è un ID cella valido.

Condizioni di errore

• Se h3CellId1Expr o h3CellId2Expr è un valore STRING che non può essere convertito in bigint o corrisponde a un valore BIGINT minore 0x08001fffffffffff o maggiore di 0x08ff3b6db6db6db6, la funzione restituisce H3_INVALID_CELL_ID.
• Se le due celle H3 di input hanno una risoluzione diversa, la funzione restituisce H3_UNDEFINED_GRID_DISTANCE.
• Se la distanza della griglia tra due celle H3 della stessa risoluzione non è definita, la funzione restituisce NULL. La distanza della griglia può essere indefinita per uno dei motivi seguenti:
  • Una delle due celle H3 di input è una cella pentagonale.
  • Le due celle H3 sono separate da una cella pentagonale.
  • Le due celle H3 sono troppo distanti l'una dall'altra.

Esempi

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

Funzioni correlate

• funzione h3_distance
• funzione h3_hexring
• funzione h3_kring
• funzione h3_kringdistances