Fonction h3_kringdistances

  • Article

S’applique à :coche marquée oui Databricks SQL oui coché Databricks Runtime 11.3 LTS et versions ultérieures

Retourne toutes les cellules H3 (représentées sous forme d’entiers ou de chaînes longs) situés à une distance de grille k de la cellule H3 d’origine, ainsi que leur distance par rapport à la cellule H3 d’origine.

Syntaxe

h3_kringdistances ( h3CellIdExpr, kExpr )

Arguments

  • h3CellIdExpr : expression BIGINT ou expression STRING hexadécimale représentant un ID de cellule H3.
  • kExpr : expression INTEGER représentant la distance de la grille. kExpr doit être non négative.

Retours

TABLEAU de structs nommés avec deux champs, cellid et distance respectivement, où le premier champ du struct correspond à un ID de cellule H3 (représenté sous forme d’entier long ou de chaîne) et le second champ à sa distance par rapport à la cellule H3 d’origine (représentée sous forme d’entier). Le type des ID de cellule H3 dans la sortie est identique au type de h3CellIdExpr.

Les éléments du TABLEAU retourné sont triés selon leur distance par rapport à la cellule H3 d’origine. Les éléments correspondant à la même distance dans le TABLEAU retourné peuvent être retournés dans n’importe quel ordre. La fonction retourne NULL si l’une des expressions d’entrée est NULL. La fonction effectue une validation partielle pour déterminer si l’argument d’entrée est un ID de cellule H3 valide. Une valeur d’ID H3 comprise entre 0x08001fffffffffff et 0x08ff3b6db6db6db6 constitue une condition nécessaire mais pas suffisante. Le comportement de la fonction n’est pas défini si l’ID de cellule d’entrée ne correspond pas à un ID de cellule valide. Si la valeur de la distance de grille est égale à zéro, le tableau retourné contient une valeur unique égale à l’ID de cellule H3 d’entrée.

Conditions d'erreur

  • Si h3CellIdExpr correspond à une CHAÎNE qui ne peut pas être convertie en BIGINT ou qui correspond à une valeur BIGINT inférieure à 0x08001fffffffffff ou supérieure à 0x08ff3b6db6db6db6, la fonction retourne H3_INVALID_CELL_ID
  • Si kExpr est négative, la fonction retourne H3_INVALID_GRID_DISTANCE_VALUE

Exemples

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