h3_kringdistances fungsi

  • Artikel

Berlaku untuk:centang ditandai ya Databricks SQL centang ditandai ya Databricks Runtime 11.3 LTS ke atas

Mengembalikan semua sel H3 (direpresentasikan sebagai bilangan bulat atau string panjang) dalam jarak k kisi dari sel H3 asal, bersama dengan jaraknya dari sel H3 asal.

Sintaks

h3_kringdistances ( h3CellIdExpr, kExpr )

Argumen

  • h3CellIdExpr: Ekspresi BIGINT, atau ekspresi STRING heksadesimal yang mewakili ID sel H3.
  • kExpr: Ekspresi BILANGAN BULAT yang mewakili jarak kisi. kExpr harus non-negatif.

Mengembalikan

ARRAY struktur bernama dengan dua bidang, bernama cellid dan distance, masing-masing, di mana bidang pertama dalam struktur adalah ID sel H3 (direpresentasikan sebagai bilangan bulat atau string panjang) dan bidang kedua dalam struktur adalah jaraknya dari sel H3 asal (direpresentasikan sebagai bilangan bulat). Jenis untuk ID sel H3 dalam output sama dengan jenis h3CellIdExpr.

Elemen dalam ARRAY yang dikembalikan diurutkan sehubungan dengan jaraknya dari sel H3 asal. Elemen yang sesuai dengan jarak yang sama dalam ARRAY yang dikembalikan dapat dikembalikan dalam urutan apa pun. Fungsi mengembalikan NULL jika salah satu ekspresi input adalah NULL. Fungsi melakukan validasi parsial mengenai apakah argumen input adalah ID sel H3 yang valid. Kondisi yang diperlukan, tetapi tidak memadai untuk ID H3 yang valid adalah bahwa nilainya antara 0x08001fffffffffff dan 0x08ff3b6db6db6db6. Perilaku fungsi tidak ditentukan jika ID sel input bukan ID sel yang valid. Jika nilai jarak kisi adalah nol, array yang dikembalikan berisi nilai tunggal yang sama dengan ID sel H3 input.

Kondisi kesalahan

  • Jika h3CellIdExpr adalah STRING yang tidak dapat dikonversi ke BIGINT atau sesuai dengan nilai BIGINT yang lebih kecil dari atau lebih besar dari 0x08001fffffffffff0x08ff3b6db6db6db6, fungsi mengembalikan H3_INVALID_CELL_ID
  • Jika kExpr negatif, fungsi mengembalikan H3_INVALID_GRID_DISTANCE_VALUE

Contoh

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