Fonction h3_kring

  • Article

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

Retourne les cellules H3 qui se trouvent à une distance (grille) k de la cellule d’origine. L’ensemble de ces cellules H3 est appelé anneau k de la cellule d’origine.

Syntaxe

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

Un TABLEAU de valeurs du même type que le type de l’expression h3CellIdExpr, correspondant aux ID de cellule H3 dotés de la même résolution que la cellule H3 d’entrée et situé à distance de la grille k de la cellule H3 d’entrée, où k correspond à la valeur de kExpr.

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 STRING 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_kring(599686042433355775, 1)
  [599686042433355775,599686030622195711,599686044580839423,599686038138388479,599686043507097599,599686015589810175,599686014516068351]

-- Simple example where the first argument is a STRING.
> SELECT h3_kring('85283473fffffff', 1)
  [85283473fffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff,8528340bfffffff]

-- First input is an invalid H3 cell ID.
> SELECT h3_kring(0, 0)
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID

-- Second input is an invalid grid distance value.
> SELECT h3_kring('85283473fffffff', -1)
  [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative