# Functions for Working with S2 Index

## S2Index​

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

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

Example

Query:

SELECT s2ToGeo(4704772434919038107) AS s2Coodrinates;

Result:

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

## s2GetNeighbors​

Returns S2 neighbor indexes 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 value

• An array consisting of 4 neighbor indexes: array[s2index1, s2index3, s2index2, s2index4]. Array(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 value

• 1 — If the cells intersect. UInt8.
• 0 — If the cells don't intersect. 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 value

• 1 — If the cap contains the S2 point index. UInt8.
• 0 — If the cap doesn't contain the S2 point index. 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 indexes 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. UInt64.
• radius — Radius of the smallest cap containing the two input caps. Float64.

Example

Query:

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

Result:

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

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. UInt64.
• s2PointHigh — Height S2 cell id corresponding to the grown rectangle. 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 value

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

## s2RectUnion​

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. UInt64.
• s2UnionRect2PointHi — High S2 cell id corresponding to the union rectangle. 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. UInt64.
• s2UnionRect2PointHi — High S2 cell id corresponding to the rectangle containing the intersection of the given rectangles. UInt64.

Example

Query:

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

Result:

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