Partager via

Fonction h3_try_distance

  • Article

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

Cette fonction se comporte de la même façon que h3_distance, sauf que la valeur NULL est retournée au lieu d’une erreur si la distance de grille entre les deux ID de cellule H3 d’entrée de la même résolution n’est pas définie. Plus précisément, elle retourne la distance de grille entre les deux ID de cellules H3 en entrée, qui sont censés être de la même résolution, ou NULL si la distance n’est pas définie.

Syntaxe

h3_try_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

Une valeur BIGINT correspondant à la distance de grille des deux cellules H3 d’entrée, qui doivent avoir la même résolution, ou NULL si la distance n’est pas définie.

La fonction renvoie NULL si l’une des expressions d’entrée est NULL. Elle valide partiellement les arguments d’entrée pour déterminer s’ils représentent des ID de cellules H3 valides. Une condition nécessaire, mais non suffisante, pour qu’un ID H3 soit valide réside dans le fait que sa valeur est comprise entre 0x08001fffffffffff et 0x08ff3b6db6db6db6. 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 les deux cellules H3 d’entrée sont de résolution différente, la fonction retourne H3_UNDEFINED_GRID_DISTANCE.
  • Si la distance de grille entre deux cellules H3 de la même résolution n’est pas définie, la fonction retourne NULL. La distance de la grille peut être indéfinie pour l’une des raisons suivantes :
    • 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))
 NULL

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

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
 NULL