Поделиться через

Функция h3_distance

  • Статья

Область применения: флажок Databricks SQL флажок Databricks Runtime 11.3 LTS и выше

Возвращает расстояние сетки двух входных идентификаторов ячеек H3.

Синтаксис

h3_distance ( h3CellId1Expr, h3CellId2Expr )

Аргументы

  • h3CellId1Expr: выражение BIGINT или шестнадцатеричное строковое выражение, представляющее идентификатор ячейки H3.
  • h3CellId2Expr: выражение BIGINT или шестнадцатеричное строковое выражение, представляющее идентификатор ячейки H3.

Возвраты

Значение BIGINT, которое является расстоянием сетки двух входных ячеек H3, которые, как ожидается, будут иметь одинаковое разрешение.

Функция возвращает значение NULL, если любое из входных выражений равно NULL. Функция выполняет частичную проверку, является ли входной аргумент действительным идентификатором ячейки H3. Необходимое, но недостаточное условие для допустимого идентификатора H3 заключается в том, что его значение находится в диапазоне от 0x08001fffffffffff до 0x08ff3b6db6db6db6. Поведение функции не определено, если какой-либо из двух идентификаторов входных ячеек не является допустимым идентификатором ячейки.

Условия ошибок

  • Если h3CellId1Expr или h3CellId2Expr является строкой, которую невозможно преобразовать в BIGINT, или соответствует значению BIGINT, которое меньше 0x08001fffffffffff или больше 0x08ff3b6db6db6db6, то функция возвращает H3_INVALID_CELL_ID.
  • Если расстояние сетки не определено, функция возвращает H3_UNDEFINED_GRID_DISTANCE. Расстояние сетки может быть не определено по следующим причинам:
    • Две входные ячейки H3 имеют разное разрешение.
    • Любая из двух входных ячеек H3 является пятиугольной ячейкой.
    • Две ячейки H3 разделяются пятиугольной ячейкой.
    • Две ячейки H3 находятся слишком далеко друг от друга.

Примеры

-- 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))
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 635723017894513407 and 635869868887430591 is undefined

-- 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)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112357393367039 and 590678880759578623 is undefined

-- Distance between two hexagons separated by a pentagon.
> SELECT h3_distance(590112494832320511, 590112632271273983)
  [H3_UNDEFINED_GRID_DISTANCE] H3 grid distance between 590112494832320511 and 590112632271273983 is undefined