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

sidebar_label
Функции для работы с индексами S2

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

S2 — это система геокодирования, в которой все географические данные представлены на трехмерной сфере (аналогично глобусу).

В библиотеке S2 точки представлены в виде индекса S2 — определенного числа, которое внутренне кодирует точку на поверхности трехмерной единичной сферы, в отличие от традиционных пар (широта, долгота). Чтобы получить индекс S2 для точки, заданной в формате (широта, долгота), используйте функцию geoToS2. Также вы можете использовать функцию s2togeo для получения географических координат, соответствующих заданному S2 индексу точки.

geoToS2

Возвращает S2 индекс точки, соответствующий заданным координатам в формате (долгота, широта).

Синтаксис

geoToS2(lon, lat)

Аргументы

• lon — долгота. Float64.
• lat — широта. Float64.

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

• S2 индекс точки.

Тип: UInt64.

Пример

Запрос:

SELECT geoToS2(37.79506683, 55.71290588) AS s2Index;

Результат:

┌─────────────s2Index─┐
│ 4704772434919038107 │
└─────────────────────┘

s2ToGeo

Возвращает географические координаты (долгота, широта), соответствующие заданному S2 индексу точки.

Синтаксис

s2ToGeo(s2index)

Аргументы

• s2index — S2 индекс. UInt64.

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

• Кортеж их двух значений: tuple(lon,lat).

Тип: lon — Float64. lat — Float64.

Пример

Запрос:

SELECT s2ToGeo(4704772434919038107) AS s2Coodrinates;

Результат:

┌─s2Coodrinates────────────────────────┐
│ (37.79506681471008,55.7129059052841) │
└──────────────────────────────────────┘

s2GetNeighbors

Возвращает S2 индексы ячеек, которые являются соседними для заданного S2 индекса. Ячейка в системе S2 представляет собой прямоугольник, ограниченный четырьмя сторонами. Соответственно, у каждой ячейки есть 4 соседние ячейки.

Синтаксис

s2GetNeighbors(s2index)

Аргументы

• s2index — S2 индекс. UInt64.

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

• Массив, содержащий 4 значения — S2 индекса соседних ячеек: array[s2index1, s2index3, s2index2, s2index4].

Тип: UInt64.

Пример

Запрос:

SELECT s2GetNeighbors(5074766849661468672) AS s2Neighbors;

Результат:

┌─s2Neighbors───────────────────────────────────────────────────────────────────────┐
│ [5074766987100422144,5074766712222515200,5074767536856236032,5074767261978329088] │
└───────────────────────────────────────────────────────────────────────────────────┘

s2CellsIntersect

Проверяет, пересекаются ли две заданные ячейки или нет.

Синтаксис

s2CellsIntersect(s2index1, s2index2)

Аргументы

• siIndex1, s2index2 — S2 индексы первой и второй ячейки. UInt64.

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

• 1 — ячейки пересекаются.
• 0 — ячейки не пересекаются.

Тип: UInt8.

Пример

Запрос:

SELECT s2CellsIntersect(9926595209846587392, 9926594385212866560) AS intersect;

Результат:

┌─intersect─┐
│         1 │
└───────────┘

s2CapContains

Определяет, содержит ли заданный купол указанную точку. Купол представляет собой часть сферы, которая была отрезана плоскостью. Купол задается точкой на сфере и радиусом в градусах.

Синтаксис

s2CapContains(center, degrees, point)

Аргументы

• center — S2 индекс точки, определяющей центр купола. UInt64.
• degrees — радиус купола в градусах. Float64.
• point — S2 индекс проверяемой точки. UInt64.

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

• 1 — купол содержит точку.
• 0 — купол не содержит точку.

Тип: UInt8.

Пример

Запрос:

SELECT s2CapContains(1157339245694594829, 1.0, 1157347770437378819) AS capContains;

Результат:

┌─capContains─┐
│           1 │
└─────────────┘

s2CapUnion

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

Синтаксис

s2CapUnion(center1, radius1, center2, radius2)

Аргументы

• center1, center2 — S2 индексы точек, определяющие два центра куполов. UInt64.
• radius1, radius2 — значения радиусов в градусах, определяющие два радиуса куполов. Float64.

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

• center — S2 индекс точки, соответствующий центру наименьшего купола, содержащего заданные купола. Тип: UInt64.
• radius — радиус в градусах наименьшего купола, содержащего заданные купола. Тип: Float64.

Пример

Запрос:

SELECT s2CapUnion(3814912406305146967, 1.0, 1157347770437378819, 1.0) AS capUnion;

Результат:

┌─capUnion───────────────────────────────┐
│ (4534655147792050737,60.2088283994957) │
└────────────────────────────────────────┘

s2RectAdd

Увеличивает размер ограничивающего прямоугольника, чтобы включить в себя точку, заданную S2 индексом. В системе S2 прямоугольник представлен типом S2Region, называемым S2LatLngRect, который задает прямоугольник в пространстве широта-долгота.

Синтаксис

s2RectAdd(s2pointLow, s2pointHigh, s2Point)

Аргументы

• s2PointLow — S2 индекс нижней точки, которая задает ограничиваюший прямоугольник. UInt64.
• s2PointHigh — S2 индекс верхний точки, которая задает ограничиваюший прямоугольник. UInt64.
• s2Point — S2 индекс целевой точки, которая будет содержаться увеличенным ограничивающим прямоугольником. UInt64.

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

• s2PointLow — идентификатор нижней S2 ячейки, соответствующий увеличенному прямоугольнику. Тип: UInt64.
• s2PointHigh — идентификатор верхней S2 ячейки, соответствующий увеличенному прямоугольнику. Тип: UInt64.

Пример

Запрос:

SELECT s2RectAdd(5178914411069187297, 5177056748191934217, 5179056748191934217) AS rectAdd;

Результат:

┌─rectAdd───────────────────────────────────┐
│ (5179062030687166815,5177056748191934217) │
└───────────────────────────────────────────┘

s2RectContains

Проверяет, содержит ли заданный прямоугольник указанную S2 точку. В системе S2 прямоугольник представлен типом S2Region, называемым S2LatLngRect, который задает прямоугольник в пространстве широта-долгота.

Синтаксис

s2RectContains(s2PointLow, s2PointHi, s2Point)

Аргументы

• s2PointLow — S2 индекс самой низкой точки, которая задает прямоугольник. UInt64.
• s2PointHigh — S2 индекс самой высокой точки, которая задает прямоугольник. UInt64.
• s2Point — S2 индекс проверяемой точки. UInt64.

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

• 1 — прямоугольник содержит заданную точку.
• 0 — прямоугольник не содержит заданную точку.

Пример

Запрос:

SELECT s2RectContains(5179062030687166815, 5177056748191934217, 5177914411069187297) AS rectContains;

Результат:

┌─rectContains─┐
│            0 │
└──────────────┘

s2RectUinion

Возвращает наименьший прямоугольник, содержащий объединение двух заданных прямоугольников. В системе S2 прямоугольник представлен типом S2Region, называемым S2LatLngRect, который задает прямоугольник в пространстве широта-долгота.

Синтаксис

s2RectUnion(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)

Аргументы

• s2Rect1PointLow, s2Rect1PointHi — значения S2 индекса для самой низкой и самой высокой точек, которые задают первый прямоугольник. UInt64.
• s2Rect2PointLow, s2Rect2PointHi — значения S2 индекса для самой низкой и самой высокой точек, которые задают второй прямоугольник. UInt64.

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

• s2UnionRect2PointLow — идентификатор нижней ячейки, соответствующей объединенному прямоугольнику. Тип: UInt64.
• s2UnionRect2PointHi — идентификатор верхней ячейки, соответствующей объединенному прямоугольнику. Тип: UInt64.

Пример

Запрос:

SELECT s2RectUnion(5178914411069187297, 5177056748191934217, 5179062030687166815, 5177056748191934217) AS rectUnion;

Результат:

┌─rectUnion─────────────────────────────────┐
│ (5179062030687166815,5177056748191934217) │
└───────────────────────────────────────────┘

s2RectIntersection

Возвращает наименьший прямоугольник, содержащий пересечение двух заданных прямоугольников. В системе S2 прямоугольник представлен типом S2Region, называемым S2LatLngRect, который задает прямоугольник в пространстве широта-долгота.

Синтаксис

s2RectIntersection(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)

Аргументы

• s2Rect1PointLow, s2Rect1PointHi — значения S2 индекса для самой низкой и самой высокой точек, которые задают первый прямоугольник. UInt64.
• s2Rect2PointLow, s2Rect2PointHi — значения S2 индекса для самой низкой и самой высокой точек, которые задают второй прямоугольник. UInt64.

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

• s2UnionRect2PointLow — идентификатор нижней ячейки, соответствующей результирующему прямоугольнику. Тип: UInt64.
• s2UnionRect2PointHi — идентификатор верхней ячейки, соответствующей результирующему прямоугольнику. Тип: UInt64.

Пример

Запрос:

SELECT s2RectIntersection(5178914411069187297, 5177056748191934217, 5179062030687166815, 5177056748191934217) AS rectIntersection;

Результат:

┌─rectIntersection──────────────────────────┐
│ (5178914411069187297,5177056748191934217) │
└───────────────────────────────────────────┘