Функции для работы с индексами H3
H3 Index
H3 — это система географической индексации, где поверхность Земли разделена на сетку равных шестиугольных ячеек. Эта система иерархическая, т.е. каждый шестиугольник на верхнем уровне ("родитель") может быть разделен на семь равных, но меньших ("детей") и так далее.
Уровень иерархии называется resolution и может принимать значение от 0 до 15, где 0 — это base уровень с самыми большими и грубыми ячейками.
Пара широты и долготы может быть преобразована в 64-битный индекс H3, идентифицирующий ячейку сетки.
Индекс H3 используется в основном для группировки местоположений и других манипуляций с геопространственными данными.
Полное описание системы H3 доступно на сайте инженерии Uber.
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.
Возвращаемые значения
- H3 индекс центрального дочернего элемента, содержащегося в данном H3 на заданном разрешении. UInt64.
Пример
Запрос:
Результат:
h3ExactEdgeLengthM
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в метрах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в метрах. Float64.
Пример
Запрос:
Результат:
h3ExactEdgeLengthKm
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в километрах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в километрах. Float64.
Пример
Запрос:
Результат:
h3ExactEdgeLengthRads
Возвращает точную длину ребра одностороннего ребра, представленного входным h3 индексом в радианах.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- Точная длина ребра в радианах. Float64.
Пример
Запрос:
Результат:
h3NumHexagons
Возвращает количество уникальных индексов H3 на данном разрешении.
Синтаксис
Параметр
resolution— разрешение индекса. Диапазон:[0, 15]. UInt8.
Возвращаемое значение
- Количество индексов H3. Int64.
Пример
Запрос:
Результат:
h3PointDistM
Возвращает "великое круговое" или "haversine" расстояние между парами точек GeoCoord (широта/долгота) в метрах.
Синтаксис
Аргументы
lat1,lon1— Широта и долгота первой точки в градусах. Float64.lat2,lon2— Широта и долгота второй точки в градусах. Float64.
Возвращаемые значения
- Расстояние haversine или великого круга в метрах. Float64.
Пример
Запрос:
Результат:
h3PointDistKm
Возвращает "великое круговое" или "haversine" расстояние между парами точек GeoCoord (широта/долгота) в километрах.
Синтаксис
Аргументы
lat1,lon1— Широта и долгота первой точки в градусах. Float64.lat2,lon2— Широта и долгота второй точки в градусах. Float64.
Возвращаемые значения
- Расстояние haversine или великого круга в километрах. Float64.
Пример
Запрос:
Результат:
h3PointDistRads
Возвращает "великое круговое" или "haversine" расстояние между парами точек GeoCoord (широта/долгота) в радианах.
Синтаксис
Аргументы
lat1,lon1— Широта и долгота первой точки в градусах. Float64.lat2,lon2— Широта и долгота второй точки в градусах. Float64.
Возвращаемые значения
- Расстояние haversine или великого круга в радианах. 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.
Возвращаемое значение
- Номер индекса одностороннего ребра H3. UInt64.
Пример
Запрос:
Результат:
h3UnidirectionalEdgeIsValid
Определяет, является ли предоставленный H3Index действительным индексом одностороннего ребра. Возвращает 1, если это одностороннее ребро, и 0 в противном случае.
Синтаксис
Параметр
index— номер индекса шестиугольника. UInt64.
Возвращаемое значение
- 1 — индекс H3 является действительным односторонним ребром. UInt8.
- 0 — индекс H3 не является действительным односторонним ребром. UInt8.
Пример
Запрос:
Результат:
h3GetOriginIndexFromUnidirectionalEdge
Возвращает исходный индекс шестиугольника из индекса одностороннего ребра H3.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего собой одностороннее ребро. UInt64.
Возвращаемое значение
- Номер исходного индекса шестиугольника. UInt64.
Пример
Запрос:
Результат:
h3GetDestinationIndexFromUnidirectionalEdge
Возвращает целевой индекс шестиугольника из индекса одностороннего ребра H3.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего собой одностороннее ребро. UInt64.
Возвращаемое значение
- Номер целевого индекса шестиугольника. UInt64.
Пример
Запрос:
Результат:
h3GetIndexesFromUnidirectionalEdge
Возвращает исходные и целевые индексы шестиугольников из данного H3 индекса одностороннего ребра.
Синтаксис
Параметр
edge— номер индекса шестиугольника, представляющего собой одностороннее ребро. UInt64.
Возвращаемое значение
Кортеж, состоящий из двух значений tuple(origin,destination):
origin— номер исходного индекса шестиугольника. UInt64.destination— номер целевого индекса шестиугольника. UInt64.
Возвращает (0,0), если предоставленный входной индекс недействителен.
Пример
Запрос:
Результат:
h3GetUnidirectionalEdgesFromHexagon
Предоставляет все односторонние ребра из предоставленного H3 индекса.
Синтаксис
Параметр
index— номер индекса шестиугольника, представляющего собой одностороннее ребро. UInt64.
Возвращаемое значение
Массив индексов h3, представляющих каждое одностороннее ребро. Array(UInt64).
Пример
Запрос:
Результат:
h3GetUnidirectionalEdgeBoundary
Возвращает координаты, определяющие унидирекциональный край.
Синтаксис
Параметр
index— Номер индекса гексагона, который представляет унидирекциональный край. UInt64.
Возвращаемое значение
Пример
Запрос:
Результат: