ClickHouse/docs/ru/query_language/functions/geo.md
alexey-milovidov 76b0a29046
Update geo.md
2019-06-30 23:53:08 +03:00

187 lines
8.0 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).
```
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)
```
```
┌─greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)─┐
│ 14132374.194975413 │
└───────────────────────────────────────────────────────────────────┘
```
## pointInEllipses
Проверяет, принадлежит ли точка хотя бы одному из эллипсов.
```
pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)
```
**Входные параметры**
- `x, y` — координаты точки на плоскости.
- `xᵢ, yᵢ` — координаты центра `i`-го эллипса.
- `aᵢ, bᵢ` — полуоси `i`-го эллипса в метрах.
Входных параметров должно быть `2+4⋅n`, где `n` — количество эллипсов.
**Возвращаемые значения**
`1`, если точка внутри хотя бы одного из эллипсов, `0`, если нет.
**Пример**
```sql
SELECT pointInEllipses(55.755831, 37.617673, 55.755831, 37.617673, 1.0, 2.0)
```
```
┌─pointInEllipses(55.755831, 37.617673, 55.755831, 37.617673, 1., 2.)─┐
│ 1 │
└─────────────────────────────────────────────────────────────────────┘
```
## pointInPolygon
Проверяет, принадлежит ли точка многоугольнику на плоскости.
```
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
```
```
┌─res─┐
│ 1 │
└─────┘
```
## geohashEncode
Кодирует широту и долготу в строку geohash, смотрите [http://geohash.org/](http://geohash.org/), [https://en.wikipedia.org/wiki/Geohash](https://en.wikipedia.org/wiki/Geohash).
```
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
```
```
┌─res──────────┐
│ ezs42d000000 │
└──────────────┘
```
## geohashDecode
Декодирует любую строку, закодированную в geohash, на долготу и широту.
**Входные значения**
- encoded string — строка, содержащая geohash.
**Возвращаемые значения**
- (longitude, latitude) — широта и долгота. Кортеж из двух значений типа `Float64`.
**Пример**
```sql
SELECT geohashDecode('ezs42') AS res
```
```
┌─res─────────────────────────────┐
│ (-5.60302734375,42.60498046875) │
└─────────────────────────────────┘
```
## geoToH3
Получает H3 индекс точки (lon, lat) с заданным разрешением
```
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]`.
**Возвращаемые значения**
Возвращает значение с типом [UInt64] (../../data_types/int_uint.md).
`0` в случае ошибки.
Иначе возвращается индексный номер шестиугольника.
**Пример**
``` sql
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```
```
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```
[Оригинальная статья](https://clickhouse.yandex/docs/ru/query_language/functions/geo/) <!--hide-->