h3_kringdistances
-functie
Van toepassing op: Databricks SQL
Databricks Runtime 11.3 LTS en hoger
Retourneert alle H3-cellen (weergegeven als lange gehele getallen of tekenreeksen) binnen de rasterafstand k
van de oorspronkelijke H3-cel, samen met de afstand van de oorspronkelijke H3-cel.
Syntaxis
h3_kringdistances ( h3CellIdExpr, kExpr )
Argumenten
-
h3CellIdExpr
: Een BIGINT-expressie of een hexadecimale TEKENREEKS-expressie die een H3-cel-id vertegenwoordigt. -
kExpr
: Een INTEGER-expressie die de rasterafstand aangeeft.kExpr
moet niet-negatief zijn.
Retouren
Een MATRIX van benoemde structs met twee velden, genaamd cellid
en distance
, waarbij het eerste veld in de struct een H3-cel-id is (weergegeven als een lang geheel getal of tekenreeks) en het tweede veld in de struct de afstand is van de oorspronkelijke H3-cel (weergegeven als een geheel getal). Het type voor de H3-cel-id's in de uitvoer is hetzelfde als het type h3CellIdExpr
.
De elementen in de geretourneerde MATRIX worden gesorteerd met betrekking tot de afstand van de oorspronkelijke H3-cel. De elementen die overeenkomen met dezelfde afstand in de geretourneerde MATRIX, kunnen in elke volgorde worden geretourneerd.
De functie retourneert NULL als een van de invoerexpressies NULL is.
De functie voert gedeeltelijke validatie uit met betrekking tot of het invoerargument een geldige H3-cel-id is. Een noodzakelijke, maar niet voldoende voorwaarde voor een geldige H3-id is dat de waarde tussen 0x08001fffffffffff
en 0x08ff3b6db6db6db6
.
Het gedrag van de functie is niet gedefinieerd als de invoercel-id geen geldige cel-id is.
Als de waarde van de rasterafstand nul is, bevat de geretourneerde matrix één waarde die gelijk is aan de cel-id van de H3-invoer.
Foutvoorwaarden
- Als
h3CellIdExpr
dit een TEKENREEKS is die niet kan worden geconverteerd naar een BIGINT of overeenkomt met een BIGINT-waarde die kleiner is dan0x08001fffffffffff
of groter0x08ff3b6db6db6db6
is, retourneert de functie H3_INVALID_CELL_ID - Als
kExpr
dit een negatief getal is, retourneert de functie H3_INVALID_GRID_DISTANCE_VALUE
Voorbeelden
-- 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