Compartir vía

Función h3_kringdistances

  • Artículo

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

Devuelve todas las celdas H3 (representadas como enteros largos o cadenas) dentro de una distancia de cuadrícula k desde la celda H3 de origen, junto con su distancia desde la celda H3 de origen.

Sintaxis

h3_kringdistances ( h3CellIdExpr, kExpr )

Argumentos

  • h3CellIdExpr: expresión BIGINT o expresión STRING hexadecimal que representa un identificador de celda H3.
  • kExpr: expresión INTEGER que representa la distancia de la cuadrícula. kExpr no puede ser negativo.

Devoluciones

Matriz ARRAY de estructuras con nombre con dos campos, denominados cellid y distance, respectivamente, donde el primer campo de la estructura es un identificador de la celda H3 (representado como un entero largo o cadena) y el segundo campo de la estructura es su distancia desde la celda H3 de origen (representada como un entero). El tipo de los identificadores de la celda H3 de la salida es el mismo que el tipo de h3CellIdExpr.

Los elementos de la matriz ARRAY devuelta se ordenan con respecto a su distancia desde la celda H3 de origen. Los elementos correspondientes a la misma distancia en la matriz ARRAY devuelta se pueden devolver en cualquier orden. La función devuelve NULL si alguna de las expresiones de entrada es NULL. La función realiza una validación parcial con respecto a si el argumento de entrada es un identificador de celda H3 válido. Una condición necesaria, pero no suficiente para un identificador H3 válido es que su valor está entre 0x08001fffffffffff y 0x08ff3b6db6db6db6. El comportamiento de la función no está definido si el identificador de celda de entrada no es un identificador de celda válido. Si el valor de la distancia de la cuadrícula es cero, la matriz devuelta contiene un valor único igual al id. de la celda H3 de entrada.

Condiciones de error

  • Si h3CellIdExpr 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 kExpr es negativo, la función devuelve H3_INVALID_GRID_DISTANCE_VALUE.

Ejemplos

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