ClickHouse/docs/ru/sql-reference/functions/geo/h3.md

toc_title
Функции для работы с индексами H3

Функции для работы с индексами H3

H3 — это система геокодирования, которая делит поверхность Земли на равные шестигранные ячейки. Система поддерживает иерархию (вложенность) ячеек, т.е. каждый "родительский" шестигранник может быть поделен на семь одинаковых вложенных "дочерних" шестигранников, и так далее.

Уровень вложенности назвается разрешением и может принимать значение от 0 до 15, где 0 соответствует базовым ячейкам самого верхнего уровня (наиболее крупным).

Для каждой точки, имеющей широту и долготу, можно получить 64-битный индекс H3, соответствующий номеру шестигранной ячейки, где эта точка находится.

Индексы H3 используются, в основном, для геопозиционирования и расчета расстояний.

h3IsValid

Проверяет корректность H3-индекса.

Синтаксис

h3IsValid(h3index)

Параметр

• h3index — идентификатор шестигранника. Тип данных: UInt64.

Возвращаемые значения

• 1 — число является H3-индексом.
• 0 — число не является H3-индексом.

Тип: UInt8.

Пример

Запрос:

SELECT h3IsValid(630814730351855103) as h3IsValid;

Результат:

┌─h3IsValid─┐
│         1 │
└───────────┘

h3GetResolution

Извлекает разрешение H3-индекса.

Синтаксис

h3GetResolution(h3index)

Параметр

• h3index — идентификатор шестигранника. Тип данных: UInt64.

Возвращаемые значения

• Разрешение сетки. Диапазон значений: [0, 15].
• Для несуществующего идентификатора может быть возвращено произвольное значение. Используйте h3IsValid для проверки идентификаторов.

Тип: UInt8.

Пример

Запрос:

SELECT h3GetResolution(639821929606596015) as resolution;

Результат:

┌─resolution─┐
│         14 │
└────────────┘

h3EdgeAngle

Рассчитывает средний размер стороны шестигранника H3 в градусах.

Синтаксис

h3EdgeAngle(resolution)

Параметр

• resolution — требуемое разрешение индекса. Тип данных: UInt8. Диапазон возможных значений: [0, 15].

Возвращаемое значение

• Средняя длина стороны шестигранника H3 в градусах. Тип данных: Float64.

Пример

Запрос:

SELECT h3EdgeAngle(10) as edgeAngle;

Результат:

┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘

h3EdgeLengthM

Рассчитывает средний размер стороны шестигранника H3 в метрах.

Синтаксис

h3EdgeLengthM(resolution)

Параметр

• resolution — требуемое разрешение индекса. Тип данных — UInt8. Диапазон возможных значений — [0, 15].

Возвращаемое значение

• Средняя длина стороны шестигранника H3 в метрах, тип — Float64.

Пример

Запрос:

SELECT h3EdgeLengthM(15) as edgeLengthM;

Результат:

┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘

geoToH3

Возвращает H3 индекс точки (lon, lat) с заданным разрешением.

Синтаксис

geoToH3(lon, lat, resolution)

Аргументы

• lon — географическая долгота. Тип данных — Float64.
• lat — географическая широта. Тип данных — Float64.
• resolution — требуемое разрешение индекса. Тип данных — UInt8. Диапазон возможных значений — [0, 15].

Возвращаемые значения

• Порядковый номер шестигранника.
• 0 в случае ошибки.

Тип данных: UInt64.

Пример

Запрос:

SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index;

Результат:

┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘

h3ToGeo

Возвращает географические координаты долготы и широты, соответствующие указанному H3-индексу.

Синтаксис

h3ToGeo(h3Index)

Аргументы

• h3Index — H3-индекс. UInt64.

Возвращаемые значения

• кортеж из двух значений: tuple(lon,lat), где lon — долгота Float64, lat — широта Float64.

Пример

Запрос:

SELECT h3ToGeo(644325524701193974) coordinates;

Результат:

┌─coordinates───────────────────────────┐
│ (37.79506616830252,55.71290243145668) │
└───────────────────────────────────────┘

h3kRing

Возвращает H3-индексы шестигранников в радиусе k от данного в произвольном порядке.

Синтаксис

h3kRing(h3index, k)

Аргументы

• h3index — идентификатор шестигранника. Тип данных: UInt64.
• k — радиус. Тип данных: целое число

Возвращаемые значения

• Массив из H3-индексов.

Тип данных: Array(UInt64).

Пример

Запрос:

SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;

Результат:

┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘

h3GetBaseCell

Определяет номер базовой (верхнеуровневой) шестиугольной H3-ячейки для указанной ячейки.

Синтаксис

h3GetBaseCell(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

Возвращаемое значение

• Индекс базовой шестиугольной ячейки.

Тип: UInt8.

Пример

Запрос:

SELECT h3GetBaseCell(612916788725809151) as basecell;

Результат:

┌─basecell─┐
│       12 │
└──────────┘

h3HexAreaM2

Определяет среднюю площадь шестиугольной H3-ячейки заданного разрешения в квадратных метрах.

Синтаксис

h3HexAreaM2(resolution)

Параметр

• resolution — разрешение. Диапазон: [0, 15]. Тип: UInt8.

Возвращаемое значение

• Площадь в квадратных метрах. Тип: Float64.

Пример

Запрос:

SELECT h3HexAreaM2(13) as area;

Результат:

┌─area─┐
│ 43.9 │
└──────┘

h3IndexesAreNeighbors

Определяет, являются ли H3-ячейки соседями.

Синтаксис

h3IndexesAreNeighbors(index1, index2)

Аргументы

• index1 — индекс шестиугольной ячейки. Тип: UInt64.
• index2 — индекс шестиугольной ячейки. Тип: UInt64.

Возвращаемое значение

• 1 — ячейки являются соседями.
• 0 — ячейки не являются соседями.

Тип: UInt8.

Пример

Запрос:

SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;

Результат:

┌─n─┐
│ 1 │
└───┘

h3ToChildren

Формирует массив дочерних (вложенных) H3-ячеек для указанной ячейки.

Синтаксис

h3ToChildren(index, resolution)

Аргументы

• index — индекс шестиугольной ячейки. Тип: UInt64.
• resolution — разрешение. Диапазон: [0, 15]. Тип: UInt8.

Возвращаемое значение

• Массив дочерних H3-ячеек.

Тип: Array(UInt64).

Пример

Запрос:

SELECT h3ToChildren(599405990164561919, 6) AS children;

Результат:

┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3ToParent

Определяет родительскую (более крупную) H3-ячейку, содержащую указанную ячейку.

Синтаксис

h3ToParent(index, resolution)

Аргументы

• index — индекс шестиугольной ячейки. Тип: UInt64.
• resolution — разрешение. Диапазон: [0, 15]. Тип: UInt8.

Возвращаемое значение

• Индекс родительской H3-ячейки.

Тип: UInt64.

Пример

Запрос:

SELECT h3ToParent(599405990164561919, 3) as parent;

Результат:

┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘

h3ToString

Преобразует H3-индекс из числового представления H3Index в строковое.

h3ToString(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

Возвращаемое значение

• Строковое представление H3-индекса.

Тип: String.

Пример

Запрос:

SELECT h3ToString(617420388352917503) as h3_string;

Результат:

┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘

stringToH3

Преобразует H3-индекс из строкового представления в числовое представление H3Index.

Синтаксис

stringToH3(index_str)

Параметр

• index_str — строковое представление H3-индекса. Тип: String.

Возвращаемое значение

• Числовое представление индекса шестиугольной ячейки.
• 0, если при преобразовании возникла ошибка.

Тип: UInt64.

Пример

Запрос:

SELECT stringToH3('89184926cc3ffff') as index;

Результат:

┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘

h3GetResolution

Определяет разрешение H3-ячейки.

Синтаксис

h3GetResolution(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

Возвращаемое значение

• Разрешение ячейки. Диапазон: [0, 15].

Тип: UInt8.

Пример

Запрос:

SELECT h3GetResolution(617420388352917503) as res;

Результат:

┌─res─┐
│   9 │
└─────┘