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

toc_title
S2 Geometry

Functions for Working with S2 Index

S2 is a geographical indexing system where all geographical data is represented on a three-dimensional sphere (similar to a globe).

In the S2 library points are represented as the S2 Index - a specific number which encodes internally a point on the surface of a unit sphere, unlike traditional (latitude, longitude) pairs. To get the S2 point index for a given point specified in the format (latitude, longitude) use the geoToS2 function. Also, you can use the s2ToGeo function for getting geographical coordinates corresponding to the specified S2 point index.

geoToS2

Returns S2 point index corresponding to the provided coordinates (longitude, latitude).

Syntax

geoToS2(lon, lat)

Arguments

• lon — Longitude. Float64.
• lat — Latitude. Float64.

Returned values

• S2 point index.

Type: UInt64.

Example

Query:

SELECT geoToS2(37.79506683, 55.71290588) AS s2Index;

Result:

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

s2ToGeo

Returns geo coordinates (longitude, latitude) corresponding to the provided S2 point index.

Syntax

s2ToGeo(s2index)

Arguments

• s2index — S2 Index. UInt64.

Returned values

• A tuple consisting of two values: tuple(lon,lat).

Type: lon — Float64. lat — Float64.

Example

Query:

SELECT s2ToGeo(4704772434919038107) AS s2Coodrinates;

Result:

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

s2GetNeighbors

Returns S2 neighbor indixes corresponding to the provided S2. Each cell in the S2 system is a quadrilateral bounded by four geodesics. So, each cell has 4 neighbors.

Syntax

s2GetNeighbors(s2index)

Arguments

• s2index — S2 Index. UInt64.

Returned values

• An array consisting of 4 neighbor indexes: array[s2index1, s2index3, s2index2, s2index4].

Type: UInt64.

Example

Query:

SELECT s2GetNeighbors(5074766849661468672) AS s2Neighbors;

Result:

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

s2CellsIntersect

Determines if the two provided S2 cells intersect or not.

Syntax

s2CellsIntersect(s2index1, s2index2)

Arguments

• siIndex1, s2index2 — S2 Index. UInt64.

Returned values

• 1 — If the cells intersect.
• 0 — If the cells don't intersect.

Type: UInt8.

Example

Query:

SELECT s2CellsIntersect(9926595209846587392, 9926594385212866560) AS intersect;

Result:

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

s2CapContains

Determines if a cap contains a S2 point. A cap represents a part of the sphere that has been cut off by a plane. It is defined by a point on a sphere and a radius in degrees.

Syntax

s2CapContains(center, degrees, point)

Arguments

• center — S2 point index corresponding to the cap. UInt64.
• degrees — Radius of the cap in degrees. Float64.
• point — S2 point index. UInt64.

Returned values

• 1 — If the cap contains the S2 point index.
• 0 — If the cap doesn't contain the S2 point index.

Type: UInt8.

Example

Query:

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

Result:

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

s2CapUnion

Determines the smallest cap that contains the given two input caps. A cap represents a portion of the sphere that has been cut off by a plane. It is defined by a point on a sphere and a radius in degrees.

Syntax

s2CapUnion(center1, radius1, center2, radius2)

Arguments

• center1, center2 — S2 point indixes corresponding to the two input caps. UInt64.
• radius1, radius2 — Radius of the two input caps in degrees. Float64.

Returned values

• center — S2 point index corresponding the center of the smallest cap containing the two input caps. Type: UInt64.
• radius — Radius of the smallest cap containing the two input caps. Type: Float64.

Example

Query:

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

Result:

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

s2RectAdd

Increases the size of the bounding rectangle to include the given S2 point. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.

Syntax

s2RectAdd(s2pointLow, s2pointHigh, s2Point)

Arguments

• s2PointLow — Low S2 point index corresponding to the rectangle. UInt64.
• s2PointHigh — High S2 point index corresponding to the rectangle. UInt64.
• s2Point — Target S2 point index that the bound rectangle should be grown to include. UInt64.

Returned values

• s2PointLow — Low S2 cell id corresponding to the grown rectangle. Type: UInt64.
• s2PointHigh — Hight S2 cell id corresponding to the grown rectangle. Type: UInt64.

Example

Query:

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

Result:

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

s2RectContains

Determines if a given rectangle contains a S2 point. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.

Syntax

s2RectContains(s2PointLow, s2PointHi, s2Point)

Arguments

• s2PointLow — Low S2 point index corresponding to the rectangle. UInt64.
• s2PointHigh — High S2 point index corresponding to the rectangle. UInt64.
• s2Point — Target S2 point index. UInt64.

Returned values

• 1 — If the rectangle contains the given S2 point.
• 0 — If the rectangle doesn't contain the given S2 point.

Example

Query:

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

Result:

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

s2RectUinion

Returns the smallest rectangle containing the union of this rectangle and the given rectangle. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.

Syntax

s2RectUnion(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)

Arguments

• s2Rect1PointLow, s2Rect1PointHi — Low and High S2 point indexes corresponding to the first rectangle. UInt64.
• s2Rect2PointLow, s2Rect2PointHi — Low and High S2 point indexes corresponding to the second rectangle. UInt64.

Returned values

• s2UnionRect2PointLow — Low S2 cell id corresponding to the union rectangle. Type: UInt64.
• s2UnionRect2PointHi — High S2 cell id corresponding to the union rectangle. Type: UInt64.

Example

Query:

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

Result:

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

s2RectIntersection

Returns the smallest rectangle containing the intersection of this rectangle and the given rectangle. In the S2 system, a rectangle is represented by a type of S2Region called a S2LatLngRect that represents a rectangle in latitude-longitude space.

Syntax

s2RectIntersection(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)

Arguments

• s2Rect1PointLow, s2Rect1PointHi — Low and High S2 point indexes corresponding to the first rectangle. UInt64.
• s2Rect2PointLow, s2Rect2PointHi — Low and High S2 point indexes corresponding to the second rectangle. UInt64.

Returned values

• s2UnionRect2PointLow — Low S2 cell id corresponding to the rectangle containing the intersection of the given rectangles. Type: UInt64.
• s2UnionRect2PointHi — High S2 cell id corresponding to the rectangle containing the intersection of the given rectangles. Type: UInt64.

Example

Query:

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

Result:

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