# 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 unit length vectors called S2 point indices (points on the surface of a three dimensional unit sphere) as opposed to traditional (latitude, longitude) pairs.

## 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 indices 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 the 4 neighbor indices: `array[s2index1, s2index3, s2index2, s2index4]`.

Type: Each S2 index is UInt64.

Example

Query:

`````` select  s2GetNeighbors(5074766849661468672) AS s2Neighbors;
``````

Result:

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

## s2CellsIntersect

Determines if the two provided S2) cell indices intersect or not.

Syntax

``````s2CellsIntersect(s2index1, s2index2)
``````

Arguments

• `siIndex1`, `s2index2` — S2 Index. UInt64.

Returned values

• 1 — If the S2 cell indices intersect.
• 0 — If the S2 cell indices don't intersect.

Type: UInt8.

Example

Query:

`````` select s2CellsIntersect(9926595209846587392, 9926594385212866560) as intersect;
``````

Result:

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

## s2CapContains

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.

Determines if a cap contains a s2 point index.

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

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.

Determines the smallest cap that contains the given two input caps.

Syntax

``````s2CapUnion(center1, radius1, center2, radius2)
``````

Arguments

• `center1`, `center2` - S2 point indices corresponding to the two input caps. UInt64.
• `radius1`, `radius2` - Radii 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) │
└────────────────────────────────────────┘
``````

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

Increases the size of the bounding rectangle to include the given S2 point index.

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{#s2RectContains}

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

Determines if a given rectangle contains a S2 point index.

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{#s2RectUnion}

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

Returns the smallest rectangle containing the union of this rectangle and the given rectangle.

Syntax

``````s2RectUnion(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)
``````

Arguments

• `s2Rect1PointLow`, `s2Rect1PointHi` - Low and High S2 point indices corresponding to the first rectangle. UInt64.
• `s2Rect2PointLow`, `s2Rect2PointHi` - Low and High S2 point indices 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{#s2RectIntersection}

Returns the smallest Rectangle containing the intersection of this rectangle and the given rectangle.

Syntax

``````s2RectIntersection(s2Rect1PointLow, s2Rect1PointHi, s2Rect2PointLow, s2Rect2PointHi)
``````

Arguments

• `s2Rect1PointLow`, `s2Rect1PointHi` - Low and High S2 point indices corresponding to the first rectangle. UInt64.
• `s2Rect2PointLow`, `s2Rect2PointHi` - Low and High S2 point indices 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` - Hi 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) │
└───────────────────────────────────────────┘
``````