Fonction h3_hexring

  • Article

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

Retourne un tableau de cellules H3 qui forment un anneau hexagonal creux centré sur la cellule H3 d’origine et qui sont à une distance de grille k de la cellule H3 d’origine.

Syntaxe

h3_hexring ( 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 formant un anneau creux centré sur la cellule H3 d’origine à la distance k, 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.
  • En présence d’un pentagone dans l’anneau kde la cellule d’origine, la fonction retourne H3_PENTAGON_ENCOUNTERED_ERROR.

Exemples

-- Simple example where the first argument is a BIGINT.
> SELECT h3_hexring(599686042433355775, 1)
  [599686014516068351,599686030622195711,599686044580839423,599686038138388479,599686043507097599,599686015589810175]

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

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

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

-- The input cell is a hexagonal cell adjacent to a pentagonal cell (the 2-ring of the hexagonal cell contains the pentagon).
> SELECT H3_HexRing('8007fffffffffff', 2)
  [H3_PENTAGON_ENCOUNTERED_ERROR] A pentagon was encountered while computing the hex ring of '8007fffffffffff' with grid distance 2