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

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

greatCircleDistance

Вычисляет расстояние между двумя точками на поверхности Земли по формуле большого круга.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

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

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

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

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

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

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

Пример

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

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

greatCircleAngle

Вычисляет угловое расстояние на сфере по формуле большого круга.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

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

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

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

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

Пример

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

┌─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, если нет.

Пример

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

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

pointInPolygon

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

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

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

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

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

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

Пример

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

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

geohashEncode

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

geohashEncode(longitude, latitude, [precision])

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

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

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

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

Пример

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

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

geohashDecode

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

geohashDecode(geohash_string)

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

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

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

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

Пример

SELECT geohashDecode('ezs42') AS res

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

h3IsValid

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

h3IsValid(h3index)

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

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

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

• 0 — число не является H3-индексом
• 1 — число является 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) с заданным разрешением.

H3 - это географическая система индексации, в которой поверхность Земли разделена на ровные шестиугольные плитки. Эта система иерархична, то есть каждый шестиугольник на верхнем уровне может быть разбит на семь еще более мелких и так далее.

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

Синтаксис

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 │
└────────────────────┘

h3kRing

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

h3kRing(h3index, k)

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

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

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

Массив из H3-индексов типа UInt64.

Пример

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

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

Оригинальная статья