ClickHouse/docs/ru/sql-reference/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

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

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

h3GetBaseCell

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

Синтаксис

h3GetBaseCell(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

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

• Индекс базовой шестиугольной ячейки.

Тип: UInt8.

Пример

Запрос:

SELECT h3GetBaseCell(612916788725809151) as basecell;

Результат:

┌─basecell─┐
│       12 │
└──────────┘

h3HexAreaM2

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

Синтаксис

h3HexAreaM2(resolution)

Параметр

• resolution — разрешение. Диапазон: [0, 15].

Тип: UInt8.

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

• Площадь в квадратных метрах. Тип: Float64.

Пример

Запрос:

SELECT h3HexAreaM2(13) as area;

Результат:

┌─area─┐
│ 43.9 │
└──────┘

h3IndexesAreNeighbors

Определяет, являются ли H3-ячейки соседями.

Синтаксис

h3IndexesAreNeighbors(index1, index2)

Параметры

• index1 — индекс шестиугольной ячейки. Тип: UInt64.
• index2 — индекс шестиугольной ячейки. Тип: UInt64.

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

• 1 — ячейки являются соседями.
• 0 — ячейки не являются соседями.

Тип: UInt8.

Пример

Запрос:

SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;

Результат:

┌─n─┐
│ 1 │
└───┘

h3ToChildren

Формирует массив дочерних (вложенных) H3-ячеек для указанной ячейки.

Синтаксис

h3ToChildren(index, resolution)

Параметры

• index — индекс шестиугольной ячейки. Тип: UInt64.
• resolution — разрешение. Диапазон: [0, 15]. Тип: UInt8.

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

• Массив дочерних H3-ячеек.

Тип: Array(UInt64).

Пример

Запрос:

SELECT h3ToChildren(599405990164561919, 6) AS children;

Результат:

┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

h3ToParent

Определяет родительскую (более крупную) H3-ячейку, содержащую указанную ячейку.

Синтаксис

h3ToParent(index, resolution)

Параметры

• index — индекс шестиугольной ячейки. Тип: UInt64.
• resolution — разрешение. Диапазон: [0, 15]. Тип: UInt8.

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

• Индекс родительской H3-ячейки.

Тип: UInt64.

Пример

Запрос:

SELECT h3ToParent(599405990164561919, 3) as parent;

Результат:

┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘

h3ToString

Преобразует H3-индекс из числового представления H3Index в строковое.

h3ToString(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

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

• Строковое представление H3-индекса.

Тип: String.

Пример

Запрос:

SELECT h3ToString(617420388352917503) as h3_string;

Результат:

┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘

stringToH3

Преобразует H3-индекс из строкового представления в числовое представление H3Index.

Синтаксис

stringToH3(index_str)

Параметр

• index_str — строковое представление H3-индекса. Тип: String.

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

• Числовое представление индекса шестиугольной ячейки.
• 0, если при преобразовании возникла ошибка.

Тип: UInt64.

Пример

Запрос:

SELECT stringToH3('89184926cc3ffff') as index;

Результат:

┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘

h3GetResolution

Определяет разрешение H3-ячейки.

Синтаксис

h3GetResolution(index)

Параметр

• index — индекс шестиугольной ячейки. Тип: UInt64.

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

• Разрешение ячейки. Диапазон: [0, 15].

Тип: UInt8.

Пример

Запрос:

SELECT h3GetResolution(617420388352917503) as res;

Результат:

┌─res─┐
│   9 │
└─────┘

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