Sdílet prostřednictvím

Funkce h3_try_distance

  • Článek

Platí pro: zaškrtnutí označeného ano Databricks SQL zaškrtnutí označeného ano Databricks Runtime 13.3 LTS a vyšší

Tato funkce se chová podobně jako h3_distance s tím rozdílem, že hodnota NULL se vrátí místo chyby, pokud není definována vzdálenost mřížky mezi dvěma vstupními ID buněk H3 stejného rozlišení. Konkrétně vrátí vzdálenost mřížky dvou vstupních ID buněk H3, u kterých se očekává stejné rozlišení, nebo hodnotu NULL, pokud vzdálenost není definována.

Syntaxe

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argumenty

  • h3CellId1Expr: Výraz BIGINT nebo šestnáctkový výraz STRING představující ID buňky H3.
  • h3CellId2Expr: Výraz BIGINT nebo šestnáctkový výraz STRING představující ID buňky H3.

Návraty

Hodnota BIGINT, která je vzdálenost mřížky dvou vstupních buněk H3, která má mít stejné rozlišení, nebo hodnotu NULL, pokud vzdálenost není definována.

Funkce vrátí hodnotu NULL, pokud některý ze vstupních výrazů má hodnotu NULL. Částečně ověří vstupní argumenty a určí, jestli představují platné ID buněk H3. Nezbytnou, ale ne dostatečnou podmínkou platného ID H3 je, že jeho hodnota je mezi 0x08001fffffffffff a 0x08ff3b6db6db6db6. Chování funkce není definováno, pokud některé ze dvou ID vstupních buněk není platné ID buňky.

Chybové podmínky

  • Pokud h3CellId1Expr nebo h3CellId2Expr je řetězec, který nelze převést na BIGINT nebo odpovídá hodnotě BIGINT, která je menší nebo větší než 0x08001fffffffffff 0x08ff3b6db6db6db6, vrátí funkce H3_INVALID_CELL_ID.
  • Pokud jsou dvě vstupní buňky H3 odlišné rozlišení, vrátí funkce H3_UNDEFINED_GRID_DISTANCE.
  • Pokud není definována vzdálenost mřížky mezi dvěma buňkami H3 stejného rozlišení, vrátí funkce hodnotu NULL. Vzdálenost mřížky může být nedefinována z některého z následujících důvodů:
    • Každá ze dvou vstupních buněk H3 je pětiúhelníková buňka.
    • Dvě buňky H3 jsou odděleny pětiúhelníkovou buňkou.
    • Obě buňky H3 jsou od sebe příliš daleko.

Příklady

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