--- toc_title: "\u0424\u0443\u043d\u043a\u0446\u0438\u0438\u0020\u0434\u043b\u044f\u0020\u0440\u0430\u0431\u043e\u0442\u044b\u0020\u0441\u0020\u0438\u043d\u0434\u0435\u043a\u0441\u0430\u043c\u0438\u0020\u0048\u0033" --- # Функции для работы с индексами H3 {#h3index} [H3](https://eng.uber.com/h3/) — это система геокодирования, которая делит поверхность Земли на равные шестигранные ячейки. Система поддерживает иерархию (вложенность) ячеек, т.е. каждый "родительский" шестигранник может быть поделен на семь одинаковых вложенных "дочерних" шестигранников, и так далее. Уровень вложенности назвается `разрешением` и может принимать значение от `0` до `15`, где `0` соответствует `базовым` ячейкам самого верхнего уровня (наиболее крупным). Для каждой точки, имеющей широту и долготу, можно получить 64-битный индекс H3, соответствующий номеру шестигранной ячейки, где эта точка находится. Индексы H3 используются, в основном, для геопозиционирования и расчета расстояний. ## h3IsValid {#h3isvalid} Проверяет корректность [H3](#h3index)-индекса. **Синтаксис** ``` sql h3IsValid(h3index) ``` **Параметр** - `h3index` — идентификатор шестигранника. Тип данных: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемые значения** - 1 — число является H3-индексом. - 0 — число не является H3-индексом. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3IsValid(630814730351855103) as h3IsValid ``` Результат: ``` text ┌─h3IsValid─┐ │ 1 │ └───────────┘ ``` ## h3GetResolution {#h3getresolution} Извлекает разрешение [H3](#h3index)-индекса. **Синтаксис** ``` sql h3GetResolution(h3index) ``` **Параметр** - `h3index` — идентификатор шестигранника. Тип данных: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемые значения** - Разрешение сетки. Диапазон значений: `[0, 15]`. - Для несуществующего идентификатора может быть возвращено произвольное значение. Используйте [h3IsValid](#h3isvalid) для проверки идентификаторов. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3GetResolution(639821929606596015) as resolution ``` Результат: ``` text ┌─resolution─┐ │ 14 │ └────────────┘ ``` ## h3EdgeAngle {#h3edgeangle} Рассчитывает средний размер стороны шестигранника [H3](#h3index) в градусах. **Синтаксис** ``` sql h3EdgeAngle(resolution) ``` **Параметр** - `resolution` — требуемое разрешение индекса. Тип данных: [UInt8](../../../sql-reference/data-types/int-uint.md). Диапазон возможных значений: `[0, 15]`. **Возвращаемое значение** - Средняя длина стороны шестигранника [H3](#h3index) в градусах. Тип данных: [Float64](../../../sql-reference/data-types/float.md). **Пример** Запрос: ``` sql SELECT h3EdgeAngle(10) as edgeAngle ``` Результат: ``` text ┌───────h3EdgeAngle(10)─┐ │ 0.0005927224846720883 │ └───────────────────────┘ ``` ## h3EdgeLengthM {#h3edgelengthm} Рассчитывает средний размер стороны шестигранника [H3](#h3index) в метрах. **Синтаксис** ``` sql h3EdgeLengthM(resolution) ``` **Параметр** - `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../../sql-reference/data-types/int-uint.md). Диапазон возможных значений — `[0, 15]`. **Возвращаемое значение** - Средняя длина стороны шестигранника H3 в метрах, тип — [Float64](../../../sql-reference/data-types/float.md). **Пример** Запрос: ``` sql SELECT h3EdgeLengthM(15) as edgeLengthM ``` Результат: ``` text ┌─edgeLengthM─┐ │ 0.509713273 │ └─────────────┘ ``` ## geoToH3 {#geotoh3} Возвращает [H3](#h3index) индекс точки `(lon, lat)` с заданным разрешением. **Синтаксис** ``` sql geoToH3(lon, lat, resolution) ``` **Параметры** - `lon` — географическая долгота. Тип данных — [Float64](../../../sql-reference/data-types/float.md). - `lat` — географическая широта. Тип данных — [Float64](../../../sql-reference/data-types/float.md). - `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../../sql-reference/data-types/int-uint.md). Диапазон возможных значений — `[0, 15]`. **Возвращаемые значения** - Порядковый номер шестигранника. - 0 в случае ошибки. Тип данных: [UInt64](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index ``` Ответ: ``` text ┌────────────h3Index─┐ │ 644325524701193974 │ └────────────────────┘ ``` ## h3kRing {#h3kring} Возвращает [H3](#h3index)-индексы шестигранников в радиусе `k` от данного в произвольном порядке. **Синтаксис** ``` sql h3kRing(h3index, k) ``` **Параметры** - `h3index` — идентификатор шестигранника. Тип данных: [UInt64](../../../sql-reference/data-types/int-uint.md). - `k` — радиус. Тип данных: [целое число](../../../sql-reference/data-types/int-uint.md) **Возвращаемые значения** - Массив из H3-индексов. Тип данных: [Array](../../../sql-reference/data-types/array.md)([UInt64](../../../sql-reference/data-types/int-uint.md)). **Пример** Запрос: ``` sql SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index ``` Результат: ``` text ┌────────────h3index─┐ │ 644325529233966508 │ │ 644325529233966497 │ │ 644325529233966510 │ │ 644325529233966504 │ │ 644325529233966509 │ │ 644325529233966355 │ │ 644325529233966354 │ └────────────────────┘ ``` ## h3GetBaseCell {#h3getbasecell} Определяет номер базовой (верхнеуровневой) шестиугольной [H3](#h3index)-ячейки для указанной ячейки. **Синтаксис** ``` sql h3GetBaseCell(index) ``` **Параметр** - `index` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Индекс базовой шестиугольной ячейки. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3GetBaseCell(612916788725809151) as basecell; ``` Результат: ``` text ┌─basecell─┐ │ 12 │ └──────────┘ ``` ## h3HexAreaM2 {#h3hexaream2} Определяет среднюю площадь шестиугольной [H3](#h3index)-ячейки заданного разрешения в квадратных метрах. **Синтаксис** ``` sql h3HexAreaM2(resolution) ``` **Параметр** - `resolution` — разрешение. Диапазон: `[0, 15]`. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Площадь в квадратных метрах. Тип: [Float64](../../../sql-reference/data-types/float.md). **Пример** Запрос: ``` sql SELECT h3HexAreaM2(13) as area; ``` Результат: ``` text ┌─area─┐ │ 43.9 │ └──────┘ ``` ## h3IndexesAreNeighbors {#h3indexesareneighbors} Определяет, являются ли [H3](#h3index)-ячейки соседями. **Синтаксис** ``` sql h3IndexesAreNeighbors(index1, index2) ``` **Параметры** - `index1` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). - `index2` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - `1` — ячейки являются соседями. - `0` — ячейки не являются соседями. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n; ``` Результат: ``` text ┌─n─┐ │ 1 │ └───┘ ``` ## h3ToChildren {#h3tochildren} Формирует массив дочерних (вложенных) [H3](#h3index)-ячеек для указанной ячейки. **Синтаксис** ``` sql h3ToChildren(index, resolution) ``` **Параметры** - `index` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). - `resolution` — разрешение. Диапазон: `[0, 15]`. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Массив дочерних H3-ячеек. Тип: [Array](../../../sql-reference/data-types/array.md)([UInt64](../../../sql-reference/data-types/int-uint.md)). **Пример** Запрос: ``` sql SELECT h3ToChildren(599405990164561919, 6) AS children; ``` Результат: ``` text ┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │ └────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ## h3ToParent {#h3toparent} Определяет родительскую (более крупную) [H3](#h3index)-ячейку, содержащую указанную ячейку. **Синтаксис** ``` sql h3ToParent(index, resolution) ``` **Параметры** - `index` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). - `resolution` — разрешение. Диапазон: `[0, 15]`. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Индекс родительской H3-ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3ToParent(599405990164561919, 3) as parent; ``` Результат: ``` text ┌─────────────parent─┐ │ 590398848891879423 │ └────────────────────┘ ``` ## h3ToString {#h3tostring} Преобразует [H3](#h3index)-индекс из числового представления `H3Index` в строковое. ``` sql h3ToString(index) ``` **Параметр** - `index` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Строковое представление H3-индекса. Тип: [String](../../../sql-reference/data-types/string.md). **Пример** Запрос: ``` sql SELECT h3ToString(617420388352917503) as h3_string; ``` Результат: ``` text ┌─h3_string───────┐ │ 89184926cdbffff │ └─────────────────┘ ``` ## stringToH3 {#stringtoh3} Преобразует [H3](#h3index)-индекс из строкового представления в числовое представление `H3Index`. **Синтаксис** ``` sql stringToH3(index_str) ``` **Параметр** - `index_str` — строковое представление H3-индекса. Тип: [String](../../../sql-reference/data-types/string.md). **Возвращаемое значение** - Числовое представление индекса шестиугольной ячейки. - `0`, если при преобразовании возникла ошибка. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT stringToH3('89184926cc3ffff') as index; ``` Результат: ``` text ┌──────────────index─┐ │ 617420388351344639 │ └────────────────────┘ ``` ## h3GetResolution {#h3getresolution} Определяет разрешение [H3](#h3index)-ячейки. **Синтаксис** ``` sql h3GetResolution(index) ``` **Параметр** - `index` — индекс шестиугольной ячейки. Тип: [UInt64](../../../sql-reference/data-types/int-uint.md). **Возвращаемое значение** - Разрешение ячейки. Диапазон: `[0, 15]`. Тип: [UInt8](../../../sql-reference/data-types/int-uint.md). **Пример** Запрос: ``` sql SELECT h3GetResolution(617420388352917503) as res; ``` Результат: ``` text ┌─res─┐ │ 9 │ └─────┘ ``` [Оригинальная статья](https://clickhouse.tech/docs/ru/sql-reference/functions/geo/h3)