h3_try_distance fungsi

  • Artikel

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

Fungsi ini bersifat mirip dengan h3_distance, kecuali bahwa NULL dikembalikan alih-alih kesalahan jika jarak kisi antara dua ID sel H3 input dengan resolusi yang sama tidak ditentukan. Secara khusus, ini mengembalikan jarak kisi dari dua ID sel H3 input, yang diharapkan memiliki resolusi yang sama, atau NULL jika jarak tidak ditentukan.

Sintaks

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argumen

  • h3CellId1Expr: Ekspresi BIGINT, atau ekspresi STRING heksadesimal yang mewakili ID sel H3.
  • h3CellId2Expr: Ekspresi BIGINT, atau ekspresi STRING heksadesimal yang mewakili ID sel H3.

Mengembalikan

Nilai BIGINT yang merupakan jarak kisi dari dua sel H3 input, yang diharapkan memiliki resolusi yang sama, atau NULL jika jarak tidak ditentukan.

Fungsi mengembalikan NULL jika salah satu ekspresi input adalah NULL. Ini sebagian memvalidasi argumen input untuk menentukan apakah argumen tersebut mewakili ID sel H3 yang valid. Yang diperlukan, tetapi tidak cukup, kondisi untuk ID H3 yang valid adalah bahwa nilainya antara 0x08001fffffffffff dan 0x08ff3b6db6db6db6. Perilaku fungsi tidak terdefinisi jika salah satu dari dua ID sel input bukan ID sel yang valid.

Kondisi kesalahan

  • Jika h3CellId1Expr atau h3CellId2Expr adalah STRING yang tidak dapat dikonversi ke BIGINT atau sesuai dengan nilai BIGINT yang lebih kecil dari 0x08001fffffffffff atau lebih besar dari 0x08ff3b6db6db6db6, fungsi mengembalikan H3_INVALID_CELL_ID.
  • Jika dua sel H3 input memiliki resolusi yang berbeda, fungsi akan mengembalikan H3_UNDEFINED_GRID_DISTANCE.
  • Jika jarak kisi antara dua sel H3 dengan resolusi yang sama tidak terdefinisi, fungsi mengembalikan NULL. Jarak kisi dapat tidak terdefinisi karena salah satu alasan berikut:
    • Salah satu dari dua sel H3 input adalah sel pentagonal.
    • Dua sel H3 dipisahkan oleh sel pentagonal.
    • Dua sel H3 terlalu jauh terpisah satu sama lain.

Contoh

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