Sdílet prostřednictvím

Funkce h3_kringdistances

  • Článek

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

Vrátí všechny buňky H3 (reprezentované jako dlouhá celá čísla nebo řetězce) ve vzdálenosti k mřížky od původní buňky H3 spolu s jejich vzdáleností od původní buňky H3.

Syntaxe

h3_kringdistances ( h3CellIdExpr, kExpr )

Argumenty

  • h3CellIdExpr: Výraz BIGINT nebo šestnáctkový výraz STRING představující ID buňky H3.
  • kExpr: Výraz INTEGER představující vzdálenost mřížky. kExpr musí být nezáporná.

Návraty

MATICE pojmenovaných struktur se dvěma poli pojmenovanými cellid a distancev uvedeném pořadí, kde první pole ve struktuře je ID buňky H3 (reprezentované jako dlouhé celé číslo nebo řetězec) a druhé pole ve struktuře je jeho vzdálenost od původní buňky H3 (reprezentované jako celé číslo). Typ ID buněk H3 ve výstupu je stejný jako typ h3CellIdExpr.

Prvky ve vrácené matici jsou seřazeny s ohledem na jejich vzdálenost od původní buňky H3. Prvky odpovídající stejné vzdálenosti ve vrácené matici mohou být vráceny v libovolném pořadí. Funkce vrátí hodnotu NULL, pokud některý ze vstupních výrazů má hodnotu NULL. Funkce provádí částečné ověření týkající se toho, jestli je vstupním argumentem platné ID buňky H3. Nezbytným, ale ne dostatečným předpokladem platného ID H3 je, že jeho hodnota je mezi 0x08001fffffffffff a 0x08ff3b6db6db6db6. Chování funkce není definováno, pokud id vstupní buňky není platné ID buňky. Pokud je hodnota vzdálenosti mřížky nula, vrácená matice obsahuje jednu hodnotu, která se rovná vstupnímu ID buňky H3.

Chybové podmínky

Příklady

-- Simple example where the first argument is a BIGINT.
> SELECT h3_kringdistances(599686042433355775, 1)
  [{"cellid":599686042433355775,"distance":0},{"cellid":599686030622195711,"distance":1},{"cellid":599686044580839423,"distance":1},{"cellid":599686038138388479,"distance":1},{"cellid":599686043507097599,"distance":1},{"cellid":599686015589810175,"distance":1},{"cellid":599686014516068351,"distance":1}]

-- Simple example where the first argument is a STRING.
> SELECT h3_kringdistances('85283473fffffff', 1)
  [{"cellid":"85283473fffffff","distance":0},{"cellid":"85283447fffffff","distance":1},{"cellid":"8528347bfffffff","distance":1},{"cellid":"85283463fffffff","distance":1},{"cellid":"85283477fffffff","distance":1},{"cellid":"8528340ffffffff","distance":1},{"cellid":"8528340bfffffff","distance":1}]

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

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