ClickHouse/docs/ru/query_language/functions/geo.md

385 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Функции для работы с географическими координатами
## 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
Вычисляет угловое расстояние на сфере по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).
```sql
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```
**Входные параметры**
- `lon1Deg` — долгота первой точки в градусах.
- `lat1Deg` — широта первой точки в градусах.
- `lon2Deg` — долгота второй точки в градусах.
- `lat2Deg` — широта второй точки в градусах.
**Возвращаемое значение**
Длина дуги большого круга между двумя точками в градусах.
**Пример**
```sql
SELECT greatCircleAngle(0, 0, 45, 0) AS arc
```
```text
┌─arc─┐
│ 45 │
└─────┘
```
## 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
Проверяет, принадлежит ли точка многоугольнику на плоскости.
```sql
pointInPolygon((x, y), [(a, b), (c, d) ...], ...)
```
**Входные значения**
- `(x, y)` — координаты точки на плоскости. Тип данных — [Tuple](../../data_types/tuple.md) — кортеж из двух чисел.
- `[(a, b), (c, d) ...]` — вершины многоугольника. Тип данных — [Array](../../data_types/array.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
Кодирует широту и долготу в строку geohash, смотрите [http://geohash.org/](http://geohash.org/), [https://en.wikipedia.org/wiki/Geohash](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
Декодирует любую строку, закодированную в 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](../../data_types/int_uint.md).
**Возвращаемые значения**
- 0 — число не является H3-индексом
- 1 — число является H3-индексом
Тип — [UInt8](../../data_types/int_uint.md).
**Пример**
```sql
SELECT h3IsValid(630814730351855103) as h3IsValid
```
```text
┌─h3IsValid─┐
│ 1 │
└───────────┘
```
## h3GetResolution
Извлекает разрешение H3-индекса.
```sql
h3GetResolution(h3index)
```
**Входные значения**
- `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../data_types/int_uint.md).
**Возвращаемые значения**
- Разрешение сетки, от 0 до 15.
- Для несуществующего идентификатора может быть возвращено произвольное значение, используйте [h3IsValid](#h3isvalid) для проверки идентификаторов
Тип — [UInt8](../../data_types/int_uint.md).
**Пример**
```sql
SELECT h3GetResolution(639821929606596015) as resolution
```
```text
┌─resolution─┐
│ 14 │
└────────────┘
```
## h3EdgeAngle
Информирует о среднем размере стороны шестигранника H3 в градусах
```sql
h3EdgeAngle(resolution)
```
**Входные значения**
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../data_types/int_uint.md). Диапазон возможных значений — `[0, 15]`.
**Возвращаемые значения**
Средняя длина стороны многоугольника H3 в градусах, тип — [Float64](../../data_types/float.md).
**Пример**
```sql
SELECT h3EdgeAngle(10) as edgeAngle
```
```text
┌─────────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘
```
## h3EdgeLengthM
Информирует о среднем размере стороны шестигранника H3 в метрах
```sql
h3EdgeLengthM(resolution)
```
**Входные значения**
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../data_types/int_uint.md). Диапазон возможных значений — `[0, 15]`.
**Возвращаемые значения**
Средняя длина стороны многоугольника H3 в метрах, тип — [Float64](../../data_types/float.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](../../data_types/float.md).
- `lat` — географическая широта. Тип данных — [Float64](../../data_types/float.md).
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../data_types/int_uint.md). Диапазон возможных значений — `[0, 15]`.
**Возвращаемые значения**
- Порядковый номер шестиугольника.
- 0 в случае ошибки.
Тип — [UInt64](../../data_types/int_uint.md).
**Пример**
Запрос:
```sql
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```
Ответ:
```text
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```
## h3kRing
Возвращает H3-индексы шестиугольников в радиусе `k` от данного в произвольном порядке
```sql
h3kRing(h3index, k)
```
**Входные значения**
- `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../data_types/int_uint.md).
- `k` — радиус. Тип данных — [целое число](../../data_types/int_uint.md)
**Возвращаемые значения**
[Массив](../../data_types/array.md) из H3-индексов типа [UInt64](../../data_types/int_uint.md).
**Пример**
```sql
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index
```
```text
┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘
```
[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/geo/) <!--hide-->