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

Функция h3_try_distance

  • Статья

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

Эта функция работает аналогично h3_distance, за исключением того, что значение NULL возвращается вместо ошибки, если расстояние сетки между двумя входными идентификаторами ячеек H3 одного разрешения не определено. В частности, он возвращает расстояние сетки двух входных идентификаторов ячеек H3, которые, как ожидается, будут иметь одно разрешение или NULL, если расстояние не определено.

Синтаксис

h3_try_distance ( h3CellId1Expr, h3CellId2Expr )

Аргументы

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

Возвраты

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

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

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

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