Funzione h3_distance

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

Restituisce la distanza della griglia dei due ID cella H3 di input.

Sintassi

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

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 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 la distanza della griglia non è definita, la funzione restituisce H3_UNDEFINED_GRID_DISTANCE. La distanza della griglia può essere indefinita per uno dei motivi seguenti:
  • Le due celle H3 di input hanno una risoluzione diversa.
  • 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))
  [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

Funzioni correlate

• funzione h3_hexring
• funzione h3_kring
• funzione h3_kringdistances
• funzione h3_try_distance