Compartir vía

h3_try_distanceFunción

  • Artículo

Se aplica a: casilla marcada como sí Databricks SQL casilla marcada como Sí Databricks Runtime 13.3 LTS y versiones posteriores

Esta función se comporta de forma similar a h3_distance, excepto que se devuelve NULL en lugar de un error si la distancia de cuadrícula entre los dos Id. de celda H3 de entrada de la misma resolución no está definida. En concreto, devuelve la distancia de cuadrícula de los dos Id. de celda H3 de entrada, que se espera que tengan la misma resolución, o NULL si la distancia no está definida.

Sintaxis

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argumentos

  • h3CellId1Expr: expresión BIGINT o expresión STRING hexadecimal que representa un identificador de celda H3.
  • h3CellId2Expr: expresión BIGINT o expresión STRING hexadecimal que representa un identificador de celda H3.

Devoluciones

Un valor BIGINT que es la distancia de cuadrícula de las dos celdas H3 de entrada, que se espera que tengan la misma resolución o NULL si la distancia no está definida.

La función devuelve NULL si cualquiera de las expresiones de entrada es NULL. Valida parcialmente los argumentos de entrada para determinar si representan Id de celda H3 válidos. Una condición necesaria, pero no suficiente, para un Id H3 válido es que su valor está entre 0x08001fffffffffff y 0x08ff3b6db6db6db6. El comportamiento de la función no está definido si cualquiera de los dos identificadores de la celda de entrada no es un identificador de celda válido.

Condiciones de error

  • Si h3CellId1Expr o h3CellId2Expr es una cadena que no se puede convertir en BIGINT o corresponde a un valor BIGINT menor que 0x08001fffffffffff o mayor que 0x08ff3b6db6db6db6, la función devuelve H3_INVALID_CELL_ID.
  • Si las dos celdas H3 de entrada tienen una resolución diferente, la función devuelve H3_UNDEFINED_GRID_DISTANCE.
  • Si la distancia de cuadrícula entre dos celdas H3 de la misma resolución no está definida, la función devuelve NULL. La distancia de la cuadrícula puede ser indefinida por cualquiera de los siguientes motivos:
    • Cualquiera de las dos celdas H3 de entrada es una celda pentagonal.
    • Las dos celdas H3 están separadas por una célula pentagonal.
    • Las dos celdas H3 están demasiado alejadas entre sí.

Ejemplos

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