Funktionen h3_try_distance

  • Artikel

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

Den här funktionen fungerar på samma sätt som h3_distance, förutom att NULL returneras i stället för ett fel om rutnätsavståndet mellan de två indata-H3-cell-ID:na med samma upplösning är odefinierat. Mer specifikt returnerar den rutnätsavståndet för de två indata-H3-cell-ID:erna, som förväntas ha samma upplösning, eller NULL om avståndet är odefinierat.

Syntax

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argument

  • h3CellId1Expr: Ett BIGINT-uttryck eller ett hexadecimalt STRING-uttryck som representerar ett H3-cell-ID.
  • h3CellId2Expr: Ett BIGINT-uttryck eller ett hexadecimalt STRING-uttryck som representerar ett H3-cell-ID.

Returer

Ett BIGINT-värde som är rutnätsavståndet för de två H3-indatacellerna, som förväntas ha samma upplösning eller NULL om avståndet är odefinierat.

Funktionen returnerar NULL om något av indatauttrycken är NULL. Den validerar delvis indataargumenten för att avgöra om de representerar giltiga H3-cell-ID:t. 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 något av de två indatacells-ID:na inte är ett giltigt cell-ID.

Feltillstånd

  • Om h3CellId1Expr eller h3CellId2Expr är en STRÄNG som inte kan konverteras till en BIGINT eller motsvarar ett BIGINT-värde som är mindre än eller större än 0x08001fffffffffff 0x08ff3b6db6db6db6returnerar funktionen H3_INVALID_CELL_ID.
  • Om de två H3-indatacellerna har olika upplösning returnerar funktionen H3_UNDEFINED_GRID_DISTANCE.
  • Om rutnätsavståndet mellan två H3-celler med samma upplösning är odefinierat returnerar funktionen NULL. Rutnätsavståndet kan vara odefinierat av någon av följande orsaker:
    • Någon av de två indata H3-cellerna är en femkantscell.
    • De två H3-cellerna separeras av en femkantscell.
    • De två H3-cellerna är för långt ifrån varandra.

Exempel

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