Partilhar via

Função h3_try_distance

  • Artigo

Aplica-se a: Marque Sim Databricks SQL Marque Sim Databricks Runtime 13.3 LTS e superior

Esta função se comporta de forma semelhante a h3_distance, exceto que NULL é retornado em vez de um erro se a distância de grade entre os dois IDs de célula H3 de entrada da mesma resolução for indefinida. Especificamente, ele retorna a distância da grade dos dois IDs de célula H3 de entrada, que devem ter a mesma resolução, ou NULL se a distância for indefinida.

Sintaxe

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Argumentos

  • h3CellId1Expr: Uma expressão BIGINT ou uma expressão STRING hexadecimal que representa um ID de célula H3.
  • h3CellId2Expr: Uma expressão BIGINT ou uma expressão STRING hexadecimal que representa um ID de célula H3.

Devoluções

Um valor BIGINT que é a distância da grade das duas células H3 de entrada, que se espera que tenham a mesma resolução, ou NULL se a distância for indefinida.

A função retorna NULL se qualquer uma das expressões de entrada for NULL. Ele valida parcialmente os argumentos de entrada para determinar se eles representam IDs de célula H3 válidos. Uma condição necessária, mas não suficiente, para um ID H3 válido é que seu valor esteja entre 0x08001fffffffffff e 0x08ff3b6db6db6db6. O comportamento da função é indefinido se qualquer um dos dois IDs de célula de entrada não é um ID de célula válido.

Condições de erro

  • Se h3CellId1Expr ou h3CellId2Expr for uma STRING que não pode ser convertida em um BIGINT ou corresponde a um valor BIGINT menor 0x08001fffffffffff ou maior que 0x08ff3b6db6db6db6, a função retorna H3_INVALID_CELL_ID.
  • Se as duas células H3 de entrada tiverem resolução diferente, a função retornará H3_UNDEFINED_GRID_DISTANCE.
  • Se a distância de grade entre duas células H3 da mesma resolução for indefinida, a função retornará NULL. A distância da grade pode ser indefinida por qualquer um dos seguintes motivos:
    • Qualquer uma das duas células H3 de entrada é uma célula pentagonal.
    • As duas células H3 são separadas por uma célula pentagonal.
    • As duas células H3 estão muito distantes uma da outra.

Exemplos

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