Fonction h3_distance

  • Article

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

Retourne la distance de grille des deux ID de cellule H3 d’entrée.

Syntaxe

h3_distance ( h3CellId1Expr, h3CellId2Expr )

Arguments

  • h3CellId1Expr : expression BIGINT ou expression STRING hexadécimale représentant un ID de cellule H3.
  • h3CellId2Expr : expression BIGINT ou expression STRING hexadécimale représentant un ID de cellule H3.

Retours

Valeur BIGINT correspondant à la distance de grille des deux cellules H3 d’entrée, qui doivent avoir la même résolution.

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’un des deux ID de cellule d’entrée ne correspond pas à un ID de cellule valide.

Conditions d'erreur

  • Si h3CellId1Expr ou h3CellId2Expr 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 la distance de la grille n’est pas définie, la fonction retourne H3_UNDEFINED_GRID_DISTANCE. La distance de la grille peut être indéfinie pour l’une des raisons suivantes :
    • Les deux cellules H3 d’entrée sont de résolution différente.
    • L’une des deux cellules d’entrée H3 est une cellule de pentagone.
    • Les deux cellules H3 sont séparées par une cellule de pentagone.
    • Les deux cellules H3 sont trop éloignées l’une de l’autre.

Exemples

-- 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))
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 635723017894513407 and 635869868887430591 is undefined

-- 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)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112357393367039 and 590678880759578623 is undefined

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112494832320511 and 590112632271273983 is undefined