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

# Функции для работы с географическими координатами {#funktsii-dlia-raboty-s-geograficheskimi-koordinatami}

## greatCircleDistance {#greatcircledistance}

Вычисляет расстояние между двумя точками на поверхности Земли по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).

``` sql
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**Входные параметры**

-   `lon1Deg` — долгота первой точки в градусах. Диапазон — `[-180°, 180°]`.
-   `lat1Deg` — широта первой точки в градусах. Диапазон — `[-90°, 90°]`.
-   `lon2Deg` — долгота второй точки в градусах. Диапазон — `[-180°, 180°]`.
-   `lat2Deg` — широта второй точки в градусах. Диапазон — `[-90°, 90°]`.

Положительные значения соответствуют северной широте и восточной долготе, отрицательные — южной широте и западной долготе.

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

Расстояние между двумя точками на поверхности Земли в метрах.

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

**Пример**

``` sql
SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)
```

``` text
┌─greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)─┐
│                                                14132374.194975413 │
└───────────────────────────────────────────────────────────────────┘
```

## greatCircleAngle {#greatcircleangle}

Вычисляет угловое расстояние на сфере по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).

``` sql
greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```

**Входные параметры**

-   `lon1Deg` — долгота первой точки в градусах.
-   `lat1Deg` — широта первой точки в градусах.
-   `lon2Deg` — долгота второй точки в градусах.
-   `lat2Deg` — широта второй точки в градусах.

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

Длина дуги большого круга между двумя точками в градусах.

**Пример**

``` sql
SELECT greatCircleAngle(0, 0, 45, 0) AS arc
```

``` text
┌─arc─┐
│  45 │
└─────┘
```

## pointInEllipses {#pointinellipses}

Проверяет, принадлежит ли точка хотя бы одному из эллипсов.
Координаты — геометрические в декартовой системе координат.

    pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)

**Входные параметры**

-   `x, y` — координаты точки на плоскости.
-   `xᵢ, yᵢ` — координаты центра `i`-го эллипса.
-   `aᵢ, bᵢ` — полуоси `i`-го эллипса (в единицах измерения координат x,y).

Входных параметров должно быть `2+4⋅n`, где `n` — количество эллипсов.

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

`1`, если точка внутри хотя бы одного из эллипсов, `0`, если нет.

**Пример**

``` sql
SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)
```

``` text
┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘
```

## pointInPolygon {#pointinpolygon}

Проверяет, принадлежит ли точка многоугольнику на плоскости.

``` sql
pointInPolygon((x, y), [(a, b), (c, d) ...], ...)
```

**Входные значения**

-   `(x, y)` — координаты точки на плоскости. Тип данных — [Tuple](../../sql-reference/functions/geo.md) — кортеж из двух чисел.
-   `[(a, b), (c, d) ...]` — вершины многоугольника. Тип данных — [Array](../../sql-reference/functions/geo.md). Каждая вершина представлена парой координат `(a, b)`. Вершины следует указывать в порядке обхода по или против часовой стрелки. Минимальное количество вершин — 3. Многоугольник должен быть константным.
-   функция поддерживает также многоугольники с дырками (вырезанными кусками). Для этого случая, добавьте многоугольники, описывающие вырезанные куски, дополнительными аргументами функции. Функция не поддерживает не односвязные многоугольники.

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

`1`, если точка внутри многоугольника, `0`, если нет.
Если точка находится на границе многоугольника, функция может возвращать как 0, так и 1.

**Пример**

``` sql
SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res
```

``` text
┌─res─┐
│   1 │
└─────┘
```

## geohashEncode {#geohashencode}

Кодирует широту и долготу в строку geohash, смотрите http://geohash.org/, https://en.wikipedia.org/wiki/Geohash.

``` sql
geohashEncode(longitude, latitude, [precision])
```

**Входные значения**

-   longitude — долгота. Диапазон — `[-180°, 180°].`
-   latitude — широта. Диапазон — `[-90°, 90°].`
-   precision — длина результирующей строки, по умолчанию `12`. Опционально. Целое число в диапазоне `[1, 12]`. Любое значение меньше, чем `1` или больше `12` автоматически преобразуются в `12`.

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

-   Строка с координатой, закодированной модифицированной версией алфавита base32.

**Пример**

``` sql
SELECT geohashEncode(-5.60302734375, 42.593994140625, 0) AS res
```

``` text
┌─res──────────┐
│ ezs42d000000 │
└──────────────┘
```

## geohashDecode {#geohashdecode}

Декодирует любую строку, закодированную в geohash, на долготу и широту.

``` sql
geohashDecode(geohash_string)
```

**Входные значения**

-   `geohash_string` — строка, содержащая geohash.

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

-   `(longitude, latitude)` — широта и долгота. Кортеж из двух значений типа `Float64`.

**Пример**

``` sql
SELECT geohashDecode('ezs42') AS res
```

``` text
┌─res─────────────────────────────┐
│ (-5.60302734375,42.60498046875) │
└─────────────────────────────────┘
```

## h3IsValid {#h3isvalid}

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

``` sql
h3IsValid(h3index)
```

**Входные значения**

-   `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).

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

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

Тип — [UInt8](../../sql-reference/functions/geo.md).

**Пример**

``` sql
SELECT h3IsValid(630814730351855103) as h3IsValid
```

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

## h3GetResolution {#h3getresolution}

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

``` sql
h3GetResolution(h3index)
```

**Входные значения**

-   `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).

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

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

Тип — [UInt8](../../sql-reference/functions/geo.md).

**Пример**

``` sql
SELECT h3GetResolution(639821929606596015) as resolution
```

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

## h3EdgeAngle {#h3edgeangle}

Информирует о среднем размере стороны шестигранника H3 в градусах

``` sql
h3EdgeAngle(resolution)
```

**Входные значения**

-   `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.

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

Средняя длина стороны многоугольника H3 в градусах, тип — [Float64](../../sql-reference/functions/geo.md).

**Пример**

``` sql
SELECT h3EdgeAngle(10) as edgeAngle
```

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

## h3EdgeLengthM {#h3edgelengthm}

Информирует о среднем размере стороны шестигранника H3 в метрах

``` sql
h3EdgeLengthM(resolution)
```

**Входные значения**

-   `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.

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

Средняя длина стороны многоугольника H3 в метрах, тип — [Float64](../../sql-reference/functions/geo.md).

**Пример**

``` sql
SELECT h3EdgeLengthM(15) as edgeLengthM
```

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

## geoToH3 {#geotoh3}

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

[H3](https://uber.github.io/h3/#/documentation/overview/introduction) - это географическая система индексации, в которой поверхность Земли разделена на ровные шестиугольные плитки. Эта система иерархична, то есть каждый шестиугольник на верхнем уровне может быть разбит на семь еще более мелких и так далее.

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

**Синтаксис**

``` sql
geoToH3(lon, lat, resolution)
```

**Параметры**

-   `lon` — географическая долгота. Тип данных — [Float64](../../sql-reference/functions/geo.md).
-   `lat` — географическая широта. Тип данных — [Float64](../../sql-reference/functions/geo.md).
-   `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.

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

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

Тип — [UInt64](../../sql-reference/functions/geo.md).

**Пример**

Запрос:

``` sql
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```

Ответ:

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

## h3kRing {#h3kring}

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

``` sql
h3kRing(h3index, k)
```

**Входные значения**

-   `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).
-   `k` — радиус. Тип данных — [целое число](../../sql-reference/functions/geo.md)

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

[Массив](../../sql-reference/functions/geo.md) из H3-индексов типа [UInt64](../../sql-reference/functions/geo.md).

**Пример**

``` sql
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index
```

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

## h3GetBaseCell {#h3getbasecell}

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

**Синтаксис**

``` 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-ячейки заданного разрешения в квадратных метрах. 

**Синтаксис**

``` 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-ячейки соседями.

**Синтаксис**

``` 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-ячеек для указанной ячейки.

**Синтаксис**

``` 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-ячейку, содержащую указанную ячейку.

**Синтаксис**

``` 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` в строковое.

``` 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`.

**Синтаксис**

``` 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-ячейки.

**Синтаксис**

``` 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/) <!--hide-->