Функции для работы с индексами 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 индекс точки (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.
Возвращаемое значение
- Номер унидирекционного ребра H3. 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.
Возвращаемое значение
Пример
Запрос:
Результат: