Функции для работы с индексами H3
H3 Index
H3 — это географическая индексная система, в которой поверхность Земли разделена на сетку равных шестиугольных ячеек. Эта система иерархична, т. е. каждый шестиугольник на верхнем уровне ("родитель") может быть разделен на семь равных, но меньших ("детей") и так далее.
Уровень иерархии называется resolution и может принимать значения от 0 до 15, где 0 является уровнем base с наибольшими и грубыми ячейками.
Пара значений широты и долготы может быть преобразована в 64-битный H3 индекс, идентифицирующий ячейку сетки.
H3 индекс используется в основном для группировки местоположений и других геопространственных манипуляций.
Полное описание системы H3 доступно на сайте Uber Engineering.
h3IsValid
Проверяет, является ли число допустимым H3 индексом.
Синтаксис
Параметр
h3index— номер индекса шестиугольника. UInt64.
Возвращаемые значения
- 1 — Число является допустимым H3 индексом. UInt8.
- 0 — Число не является допустимым H3 индексом. UInt8.
Пример
Запрос:
Результат:
h3GetResolution
Определяет разрешение данного H3 индекса.
Синтаксис
Параметр
h3index— номер индекса шестиугольника. UInt64.
Возвращаемые значения
- Разрешение индекса. Диапазон:
[0, 15]. UInt8. - Если индекс недействителен, функция возвращает случайное значение. Используйте h3IsValid для проверки индекса. UInt8.
Пример
Запрос:
Результат:
h3EdgeAngle
Вычисляет среднюю длину ребра H3 шестиугольника в градусах.
Синтаксис
Параметр
resolution— разрешение индекса. UInt8. Диапазон:[0, 15].
Возвращаемые значения
Пример
Запрос:
Результат:
h3EdgeLengthM
Вычисляет среднюю длину ребра H3 шестиугольника в метрах.
Синтаксис
Параметр
resolution— разрешение индекса. UInt8. Диапазон:[0, 15].
Возвращаемые значения
Пример
Запрос:
Результат:
h3EdgeLengthKm
Вычисляет среднюю длину ребра H3 шестиугольника в километрах.
Синтаксис
Параметр
resolution— разрешение индекса. UInt8. Диапазон:[0, 15].
Возвращаемые значения
Пример
Запрос:
Результат:
geoToH3
Возвращает H3 индекс точки (lat, lon) с заданным разрешением.
Синтаксис
Аргументы
lat— Широта. Float64.lon— Долгота. Float64.resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемые значения
Примечание: В ClickHouse v25.4 или младше, geoToH3() принимает значения в порядке (lon, lat). В ClickHouse v25.5 входные значения принимаются в порядке (lat, lon). Предыдущее поведение может быть восстановлено с помощью настройки geotoh3_lon_lat_input_order = true.
Пример
Запрос:
Результат:
h3ToGeo
Возвращает координаты центра (широта и долгота), соответствующие предоставленному H3 индексу.
Синтаксис
Аргументы
h3Index— H3 индекс. UInt64.
Возвращаемые значения
Примечание: В ClickHouse v24.12 или младше, h3ToGeo() возвращает значения в порядке (lon, lat). В ClickHouse v25.1 возвращаемые значения идут в порядке (lat, lon). Предыдущее поведение можно восстановить с помощью настройки h3togeo_lon_lat_result_order = true.
Пример
Запрос:
Результат:
h3ToGeoBoundary
Возвращает массив пар (lat, lon), который соответствует границе заданного H3 индекса.
Синтаксис
Аргументы
h3Index— H3 индекс. UInt64.
Возвращаемые значения
Пример
Запрос:
Результат:
h3kRing
Списывает все H3 шестиугольники в радиусе k от заданного шестиугольника в случайном порядке.
Синтаксис
Аргументы
Возвращаемые значения
Пример
Запрос:
Результат:
h3GetBaseCell
Возвращает номер базовой ячейки H3 индекса.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Номер базовой ячейки шестиугольника. UInt8.
Пример
Запрос:
Результат:
h3HexAreaM2
Возвращает среднюю площадь шестиугольника в квадратных метрах при заданном разрешении.
Синтаксис
Параметр
resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
- Площадь в квадратных метрах. Float64.
Пример
Запрос:
Результат:
h3HexAreaKm2
Возвращает среднюю площадь шестиугольника в квадратных километрах при заданном разрешении.
Синтаксис
Параметр
resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
- Площадь в квадратных километрах. Float64.
Пример
Запрос:
Результат:
h3IndexesAreNeighbors
Возвращает, являются ли предоставленные H3 индексы соседями.
Синтаксис
Аргументы
Возвращаемое значение
Пример
Запрос:
Результат:
h3ToChildren
Возвращает массив дочерних индексов для данного H3 индекса.
Синтаксис
Аргументы
index— номер индекса шестиугольника. UInt64.resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемые значения
Пример
Запрос:
Результат:
h3ToParent
Возвращает родительский (более крупный) индекс, содержащий данный H3 индекс.
Синтаксис
Аргументы
index— номер индекса шестиугольника. UInt64.resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
- Родительский H3 индекс. UInt64.
Пример
Запрос:
Результат:
h3ToString
Преобразует представление H3Index индекса в строковое представление.
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Строковое представление H3 индекса. String.
Пример
Запрос:
Результат:
stringToH3
Преобразует строковое представление в представление H3Index (UInt64).
Синтаксис
Параметр
index_str— строковое представление H3 индекса. String.
Возвращаемое значение
- Номер шестиугольного индекса. Возвращает 0 в случае ошибки. UInt64.
Пример
Запрос:
Результат:
h3GetResolution
Возвращает разрешение H3 индекса.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Разрешение индекса. Диапазон:
[0, 15]. UInt8.
Пример
Запрос:
Результат:
h3IsResClassIII
Возвращает, имеет ли H3 индекс разрешение с ориентацией Class III.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
1— Индекс имеет разрешение с ориентацией Class III. UInt8.0— Индекс не имеет разрешения с ориентацией Class III. UInt8.
Пример
Запрос:
Результат:
h3IsPentagon
Возвращает, представляет ли этот H3 индекс пятиугольную ячейку.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
1— Индекс представляет собой пятиугольную ячейку. UInt8.0— Индекс не представляет собой пятиугольную ячейку. UInt8.
Пример
Запрос:
Результат:
h3GetFaces
Возвращает грани икосаэдра, пересекаемые заданным H3 индексом.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемые значения
Пример
Запрос:
Результат:
h3CellAreaM2
Возвращает точную площадь конкретной ячейки в квадратных метрах, соответствующей заданному входному H3 индексу.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Площадь ячейки в квадратных метрах. Float64.
Пример
Запрос:
Результат:
h3CellAreaRads2
Возвращает точную площадь конкретной ячейки в квадратных радианах, соответствующей заданному входному H3 индексу.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Площадь ячейки в квадратных радианах. Float64.
Пример
Запрос:
Результат:
h3ToCenterChild
Возвращает индекс центрального дочернего (более тонкого) H3 индекса, содержащегося в данном H3 по заданному разрешению.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемые значения
Пример
Запрос:
Результат:
h3ExactEdgeLengthM
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в метрах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в метрах. Float64.
Пример
Запрос:
Результат:
h3ExactEdgeLengthKm
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в километрах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в километрах. Float64.
Пример
Запрос:
Результат:
h3ExactEdgeLengthRads
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в радианах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в радианах. Float64.
Пример
Запрос:
Результат:
h3NumHexagons
Возвращает количество уникальных H3 индексов при заданном разрешении.
Синтаксис
Параметр
resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
- Количество H3 индексов. Int64.
Пример
Запрос:
Результат:
h3PointDistM
Возвращает расстояние "по большой окружности" или "по формуле гаверсина" между парами точек GeoCoord (широта/долгота) в метрах.
Синтаксис
Аргументы
lat1,lon1— широта и долгота точки1 в градусах. Float64.lat2,lon2— широта и долгота точки2 в градусах. Float64.
Возвращаемые значения
- расстояние гаверсина или по большой окружности в метрах.Float64.
Пример
Запрос:
Результат:
h3PointDistKm
Возвращает расстояние "по большой окружности" или "по формуле гаверсина" между парами точек GeoCoord (широта/долгота) в километрах.
Синтаксис
Аргументы
lat1,lon1— широта и долгота точки1 в градусах. Float64.lat2,lon2— широта и долгота точки2 в градусах. Float64.
Возвращаемые значения
- расстояние гаверсина или по большой окружности в километрах. Float64.
Пример
Запрос:
Результат:
h3PointDistRads
Возвращает расстояние "по большой окружности" или "по формуле гаверсина" между парами точек GeoCoord (широта/долгота) в радианах.
Синтаксис
Аргументы
lat1,lon1— широта и долгота точки1 в градусах. Float64.lat2,lon2— широта и долгота точки2 в градусах. Float64.
Возвращаемые значения
- расстояние гаверсина или по большой окружности в радианах. Float64.
Пример
Запрос:
Результат:
h3GetRes0Indexes
Возвращает массив всех H3 индексов разрешения 0.
Синтаксис
Возвращаемые значения
Пример
Запрос:
Результат:
h3GetPentagonIndexes
Возвращает все пятиугольные H3 индексы при указанном разрешении.
Синтаксис
Параметр
resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
Пример
Запрос:
Результат:
h3Line
Возвращает линию индексов между двумя предоставленными индексами.
Синтаксис
Параметр
start— номер индекса шестиугольника, представляющего начальную точку. UInt64.end— номер индекса шестиугольника, представляющего конечную точку. UInt64.
Возвращаемое значение
Массив индексов h3, представляющих линию индексов между двумя предоставленными индексами. Array(UInt64).
Пример
Запрос:
Результат:
h3Distance
Возвращает расстояние в ячейках сетки между двумя предоставленными индексами.
Синтаксис
Параметр
start— номер индекса шестиугольника, представляющего начальную точку. UInt64.end— номер индекса шестиугольника, представляющего конечную точку. UInt64.
Возвращаемое значение
- Количество ячеек сетки. Int64.
Возвращает отрицательное число, если вычисление расстояния невозможно.
Пример
Запрос:
Результат:
h3HexRing
Возвращает индексы шестиугольного кольца, центрированного на предоставленном исходном h3Index и длины k.
Возвращает 0, если никаких пятиугольных искажений не возникло.
Синтаксис
Параметр
index— номер индекса шестиугольника, представляющего исходную точку. UInt64.k— расстояние. UInt64.
Возвращаемые значения
Пример
Запрос:
Результат:
h3GetUnidirectionalEdge
Возвращает односторонний ребровой H3 индекс на основе предоставленного исходного и конечного индексов и возвращает 0 в случае ошибки.
Синтаксис
Параметр
originIndex— номер исходного индекса шестиугольника. UInt64.destinationIndex— номер конечного индекса шестиугольника. UInt64.
Возвращаемое значение
- Номер одностороннего ребрового шестиугольного индекса. UInt64.
Пример
Запрос:
Результат:
h3UnidirectionalEdgeIsValid
Определяет, является ли предоставленный H3Index допустимым индексом одностороннего ребра. Возвращает 1, если это одностороннее ребро, и 0 в противном случае.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- 1 — H3 индекс является допустимым односторонним ребром. UInt8.
- 0 — H3 индекс не является допустимым односторонним ребром. UInt8.
Пример
Запрос:
Результат:
h3GetOriginIndexFromUnidirectionalEdge
Возвращает исходный шестиугольный индекс из одностороннего ребрового H3Index.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего одностороннее ребро. UInt64.
Возвращаемое значение
- Номер исходного шестиугольного индекса. UInt64.
Пример
Запрос:
Результат:
h3GetDestinationIndexFromUnidirectionalEdge
Возвращает конечный шестиугольный индекс из одностороннего ребрового H3Index.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего одностороннее ребро. UInt64.
Возвращаемое значение
- Номер конечного шестиугольного индекса. UInt64.
Пример
Запрос:
Результат:
h3GetIndexesFromUnidirectionalEdge
Возвращает исходные и конечные шестиугольные индексы из заданного одностороннего ребрового H3Index.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего одностороннее ребро. UInt64.
Возвращаемое значение
Кортеж, состоящий из двух значений tuple(origin, destination):
origin— номер исходного шестиугольного индекса. UInt64.destination— номер конечного шестиугольного индекса. UInt64.
Возвращает (0,0), если предоставленный ввод недействителен.
Пример
Запрос:
Результат:
h3GetUnidirectionalEdgesFromHexagon
Предоставляет все односторонние ребра из предоставленного H3Index.
Синтаксис
Параметр
index— номер индекса шестиугольника, представляющего одностороннее ребро. UInt64.
Возвращаемое значение
Массив индексов h3, представляющих каждое одностороннее ребро. Array(UInt64).
Пример
Запрос:
Результат:
h3GetUnidirectionalEdgeBoundary
Возвращает координаты, определяющие направленное ребро.
Синтаксис
Параметр
index— Номер индекса гексагона, который представляет направленное ребро. UInt64.
Возвращаемое значение
Пример
Запрос:
Результат:
