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

Функция h3_kringdistances

  • Статья

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

Возвращает все ячейки H3 (представленные как длинные целые числа или строки) в пределах расстояния сетки k от исходной ячейки H3, а также их расстояние от исходной ячейки H3.

Синтаксис

h3_kringdistances ( h3CellIdExpr, kExpr )

Аргументы

  • h3CellIdExpr: выражение BIGINT или шестнадцатеричное строковое выражение, представляющее идентификатор ячейки H3.
  • kExpr: выражение INTEGER, представляющее расстояние сетки. Значение kExpr не должно быть отрицательным.

Возвраты

Массив именованных структур с двумя полями с именами cellid и distanceсоответственно, where первое поле структуры — это идентификатор ячейки H3 (представленный как длинное целое число или строка), а второе поле в структуре — это расстояние от ячейки H3 источника (представленное как целое число). Тип идентификаторов ячеек H3 в выходных данных совпадает с типом h3CellIdExpr.

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

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

  • Если h3CellIdExpr — это строка, которая не может быть преобразована в BIGINT или соответствует значению BIGINT, которое меньше 0x08001fffffffffff или больше 0x08ff3b6db6db6db6, функция возвращает H3_INVALID_CELL_ID
  • Если значение kExpr отрицательное, функция возвращает H3_INVALID_GRID_DISTANCE_VALUE

Примеры

-- Simple example where the first argument is a BIGINT.
> SELECT h3_kringdistances(599686042433355775, 1)
  [{"cellid":599686042433355775,"distance":0},{"cellid":599686030622195711,"distance":1},{"cellid":599686044580839423,"distance":1},{"cellid":599686038138388479,"distance":1},{"cellid":599686043507097599,"distance":1},{"cellid":599686015589810175,"distance":1},{"cellid":599686014516068351,"distance":1}]

-- Simple example where the first argument is a STRING.
> SELECT h3_kringdistances('85283473fffffff', 1)
  [{"cellid":"85283473fffffff","distance":0},{"cellid":"85283447fffffff","distance":1},{"cellid":"8528347bfffffff","distance":1},{"cellid":"85283463fffffff","distance":1},{"cellid":"85283477fffffff","distance":1},{"cellid":"8528340ffffffff","distance":1},{"cellid":"8528340bfffffff","distance":1}]

-- First input is an invalid H3 cell ID.
> SELECT h3_kringdistances(0, 0)
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID

-- Second input is an invalid grid distance value.
> SELECT h3_kringdistances('85283473fffffff', -1)
  [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative