Функции для работы с H3 индексами
H3 Индекс
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 индекс точки (lon, lat) с указанным разрешением.
Синтаксис
Аргументы
lon— Долгота. Float64.lat— Широта. Float64.resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемые значения
Пример
Запрос:
Результат:
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.
Возвращаемое значение
Пример
Запрос:
Результат: