Funktionen h3_kringdistances

  • Artikel

Gäller för: markerad ja Databricks SQL markerad ja Databricks Runtime 11.3 LTS och senare

Returnerar alla H3-celler (representeras som långa heltal eller strängar) inom rutnätsavståndet k från ursprungscellen H3, tillsammans med avståndet från ursprungscellen H3.

Syntax

h3_kringdistances ( h3CellIdExpr, kExpr )

Argument

  • h3CellIdExpr: Ett BIGINT-uttryck eller ett hexadecimalt STRING-uttryck som representerar ett H3-cell-ID.
  • kExpr: Ett INTEGER-uttryck som representerar rutnätsavståndet. kExpr måste vara icke-negativ.

Returer

En MATRIS med namngivna structs med två fält, med namnet cellid respektive distance, där det första fältet i structen är ett H3-cell-ID (representerat som ett långt heltal eller en sträng) och det andra fältet i structen är dess avstånd från H3-ursprungscellen (representeras som ett heltal). Typen för H3-cell-ID:t i utdata är samma som typen av h3CellIdExpr.

Elementen i den returnerade MATRISen sorteras med avseende på deras avstånd från ursprungscellen H3. De element som motsvarar samma avstånd i den returnerade MATRISen kan returneras i valfri ordning. Funktionen returnerar NULL om något av indatauttrycken är NULL. Funktionen validerar delvis om indataargumentet är ett giltigt H3-cell-ID. Ett nödvändigt men inte tillräckligt villkor för ett giltigt H3-ID är att dess värde är mellan 0x08001fffffffffff och 0x08ff3b6db6db6db6. Funktionens beteende är odefinierat om indatacells-ID:t inte är ett giltigt cell-ID. Om värdet för rutnätsavståndet är noll innehåller den returnerade matrisen ett enda värde som är lika med indata-H3-cell-ID:t.

Feltillstånd

Exempel

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