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

386 lines
14 KiB
Markdown
Raw Normal View History

# Функции для работы с географическими координатами {#funktsii-dlia-raboty-s-geograficheskimi-koordinatami}
2018-05-10 16:51:45 +00:00
## greatCircleDistance {#greatcircledistance}
2018-05-10 16:51:45 +00:00
Вычисляет расстояние между двумя точками на поверхности Земли по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).
``` sql
2018-05-10 16:51:45 +00:00
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```
**Входные параметры**
- `lon1Deg` — долгота первой точки в градусах. Диапазон — `[-180°, 180°]`.
- `lat1Deg` — широта первой точки в градусах. Диапазон — `[-90°, 90°]`.
- `lon2Deg` — долгота второй точки в градусах. Диапазон — `[-180°, 180°]`.
- `lat2Deg` — широта второй точки в градусах. Диапазон — `[-90°, 90°]`.
2018-05-10 16:51:45 +00:00
Положительные значения соответствуют северной широте и восточной долготе, отрицательные — южной широте и западной долготе.
**Возвращаемое значение**
Расстояние между двумя точками на поверхности Земли в метрах.
Генерирует исключение, когда значения входных параметров выходят за границы диапазонов.
**Пример**
``` sql
2018-05-10 16:51:45 +00:00
SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)
```
``` text
2018-05-10 16:51:45 +00:00
┌─greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673)─┐
│ 14132374.194975413 │
└───────────────────────────────────────────────────────────────────┘
```
## greatCircleAngle {#greatcircleangle}
2019-12-05 13:25:47 +00:00
Вычисляет угловое расстояние на сфере по [формуле большого круга](https://en.wikipedia.org/wiki/Great-circle_distance).
``` sql
2019-12-05 13:25:47 +00:00
greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)
```
**Входные параметры**
- `lon1Deg` — долгота первой точки в градусах.
- `lat1Deg` — широта первой точки в градусах.
- `lon2Deg` — долгота второй точки в градусах.
- `lat2Deg` — широта второй точки в градусах.
2019-12-05 13:25:47 +00:00
**Возвращаемое значение**
Длина дуги большого круга между двумя точками в градусах.
**Пример**
``` sql
2019-12-05 13:25:47 +00:00
SELECT greatCircleAngle(0, 0, 45, 0) AS arc
```
``` text
2019-12-05 13:25:47 +00:00
┌─arc─┐
│ 45 │
└─────┘
```
## pointInEllipses {#pointinellipses}
2018-05-10 16:51:45 +00:00
Проверяет, принадлежит ли точка хотя бы одному из эллипсов.
Координаты — геометрические в декартовой системе координат.
2018-05-10 16:51:45 +00:00
pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ)
2018-05-10 16:51:45 +00:00
**Входные параметры**
- `x, y` — координаты точки на плоскости.
- `xᵢ, yᵢ` — координаты центра `i`-го эллипса.
- `aᵢ, bᵢ` — полуоси `i`-го эллипса (в единицах измерения координат x,y).
2018-05-10 16:51:45 +00:00
Входных параметров должно быть `2+4⋅n`, где `n` — количество эллипсов.
**Возвращаемые значения**
`1`, если точка внутри хотя бы одного из эллипсов, `0`, если нет.
2018-08-13 14:51:06 +00:00
**Пример**
2018-05-10 16:51:45 +00:00
``` sql
SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)
2018-05-10 16:51:45 +00:00
```
``` text
┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│ 1 │
└─────────────────────────────────────────────────┘
2018-05-10 16:51:45 +00:00
```
2018-08-13 14:51:06 +00:00
## pointInPolygon {#pointinpolygon}
2018-08-13 14:51:06 +00:00
2018-08-14 14:52:38 +00:00
Проверяет, принадлежит ли точка многоугольнику на плоскости.
2018-08-13 14:51:06 +00:00
``` sql
2018-08-14 14:52:38 +00:00
pointInPolygon((x, y), [(a, b), (c, d) ...], ...)
2018-08-13 14:51:06 +00:00
```
**Входные значения**
- `(x, y)` — координаты точки на плоскости. Тип данных — [Tuple](../../sql-reference/functions/geo.md) — кортеж из двух чисел.
- `[(a, b), (c, d) ...]` — вершины многоугольника. Тип данных — [Array](../../sql-reference/functions/geo.md). Каждая вершина представлена парой координат `(a, b)`. Вершины следует указывать в порядке обхода по или против часовой стрелки. Минимальное количество вершин — 3. Многоугольник должен быть константным.
- функция поддерживает также многоугольники с дырками (вырезанными кусками). Для этого случая, добавьте многоугольники, описывающие вырезанные куски, дополнительными аргументами функции. Функция не поддерживает не односвязные многоугольники.
2018-08-13 14:51:06 +00:00
**Возвращаемые значения**
`1`, если точка внутри многоугольника, `0`, если нет.
2018-08-14 14:52:38 +00:00
Если точка находится на границе многоугольника, функция может возвращать как 0, так и 1.
2018-08-13 14:51:06 +00:00
**Пример**
``` sql
2018-08-13 14:51:06 +00:00
SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res
```
``` text
2018-08-13 14:51:06 +00:00
┌─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}
2019-12-05 10:12:46 +00:00
Проверяет корректность H3-индекса.
``` sql
2019-12-05 10:12:46 +00:00
h3IsValid(h3index)
```
**Входные значения**
- `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).
2019-12-05 10:12:46 +00:00
**Возвращаемые значения**
- 0 — число не является H3-индексом
- 1 — число является H3-индексом
2019-12-05 10:12:46 +00:00
Тип — [UInt8](../../sql-reference/functions/geo.md).
2019-12-05 10:12:46 +00:00
**Пример**
``` sql
2019-12-05 10:12:46 +00:00
SELECT h3IsValid(630814730351855103) as h3IsValid
```
``` text
2019-12-05 10:12:46 +00:00
┌─h3IsValid─┐
│ 1 │
└───────────┘
```
## h3GetResolution {#h3getresolution}
2019-12-05 10:01:21 +00:00
Извлекает разрешение H3-индекса.
``` sql
2019-12-05 10:01:21 +00:00
h3GetResolution(h3index)
```
**Входные значения**
- `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).
2019-12-05 10:01:21 +00:00
**Возвращаемые значения**
- Разрешение сетки, от 0 до 15.
- Для несуществующего идентификатора может быть возвращено произвольное значение, используйте [h3IsValid](#h3isvalid) для проверки идентификаторов
2019-12-05 10:01:21 +00:00
Тип — [UInt8](../../sql-reference/functions/geo.md).
2019-12-05 10:01:21 +00:00
**Пример**
``` sql
2019-12-05 10:01:21 +00:00
SELECT h3GetResolution(639821929606596015) as resolution
```
``` text
2019-12-05 10:01:21 +00:00
┌─resolution─┐
│ 14 │
└────────────┘
```
## h3EdgeAngle {#h3edgeangle}
2019-12-05 13:25:47 +00:00
Информирует о среднем размере стороны шестигранника H3 в градусах
``` sql
2019-12-05 13:25:47 +00:00
h3EdgeAngle(resolution)
```
**Входные значения**
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.
2019-12-05 13:25:47 +00:00
**Возвращаемые значения**
Средняя длина стороны многоугольника H3 в градусах, тип — [Float64](../../sql-reference/functions/geo.md).
2019-12-05 13:25:47 +00:00
**Пример**
``` sql
2019-12-05 13:25:47 +00:00
SELECT h3EdgeAngle(10) as edgeAngle
```
``` text
2019-12-05 13:25:47 +00:00
┌─────────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘
```
## h3EdgeLengthM {#h3edgelengthm}
2019-12-05 13:23:50 +00:00
Информирует о среднем размере стороны шестигранника H3 в метрах
``` sql
2019-12-05 13:23:50 +00:00
h3EdgeLengthM(resolution)
```
**Входные значения**
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.
2019-12-05 13:23:50 +00:00
**Возвращаемые значения**
Средняя длина стороны многоугольника H3 в метрах, тип — [Float64](../../sql-reference/functions/geo.md).
2019-12-05 13:23:50 +00:00
**Пример**
``` sql
2019-12-05 13:23:50 +00:00
SELECT h3EdgeLengthM(15) as edgeLengthM
```
``` text
2019-12-05 13:23:50 +00:00
┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘
```
## geoToH3 {#geotoh3}
2019-03-25 14:34:52 +00:00
Возвращает H3 индекс точки `(lon, lat)` с заданным разрешением.
[H3](https://uber.github.io/h3/#/documentation/overview/introduction) - это географическая система индексации, в которой поверхность Земли разделена на ровные шестиугольные плитки. Эта система иерархична, то есть каждый шестиугольник на верхнем уровне может быть разбит на семь еще более мелких и так далее.
H3 индекс используется в основном для определения местоположения с помощью карт и других геопространственных манипуляций.
**Синтаксис**
2019-03-25 14:34:52 +00:00
``` sql
2019-06-30 20:46:29 +00:00
geoToH3(lon, lat, resolution)
2019-03-25 14:34:52 +00:00
```
**Параметры**
2019-03-25 14:34:52 +00:00
- `lon` — географическая долгота. Тип данных — [Float64](../../sql-reference/functions/geo.md).
- `lat` — географическая широта. Тип данных — [Float64](../../sql-reference/functions/geo.md).
- `resolution` — требуемое разрешение индекса. Тип данных — [UInt8](../../sql-reference/functions/geo.md). Диапазон возможных значений — `[0, 15]`.
2019-03-25 14:34:52 +00:00
**Возвращаемые значения**
- Порядковый номер шестиугольника.
- 0 в случае ошибки.
Тип — [UInt64](../../sql-reference/functions/geo.md).
2019-03-25 14:34:52 +00:00
**Пример**
Запрос:
``` sql
2019-06-30 20:46:29 +00:00
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
2019-03-25 14:34:52 +00:00
```
Ответ:
``` text
2019-03-25 14:34:52 +00:00
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```
## h3kRing {#h3kring}
2019-12-05 10:46:39 +00:00
Возвращает H3-индексы шестиугольников в радиусе `k` от данного в произвольном порядке
``` sql
2019-12-05 10:46:39 +00:00
h3kRing(h3index, k)
```
2019-12-05 10:46:39 +00:00
**Входные значения**
- `h3index` — идентификатор шестиугольника. Тип данных — [UInt64](../../sql-reference/functions/geo.md).
- `k` — радиус. Тип данных — [целое число](../../sql-reference/functions/geo.md)
2019-12-05 10:46:39 +00:00
**Возвращаемые значения**
[Массив](../../sql-reference/functions/geo.md) из H3-индексов типа [UInt64](../../sql-reference/functions/geo.md).
2019-12-05 10:46:39 +00:00
**Пример**
``` sql
2019-12-05 10:46:39 +00:00
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index
```
``` text
2019-12-05 10:46:39 +00:00
┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘
```
2020-01-30 10:34:55 +00:00
[Оригинальная статья](https://clickhouse.tech/docs/ru/query_language/functions/geo/) <!--hide-->