Docs - S2 functions

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

@@ -0,0 +1,120 @@
+--- 
+toc_title: S2 Geometry
+---
+
+# Functions for Working with S2 Index {#s2Index}
+
+[S2](https://s2geometry.io/) is a geographical indexing system where all geographical data is represented on a three-dimensional sphere (similar to a globe).
+
+## geoToS2 {#geoToS2}
+
+Returns [S2](#s2index) point index corresponding to the provided coordinates `(longitude, latitude)`.
+
+**Syntax**
+
+``` sql
+geoToS2(lon, lat)
+```
+
+**Arguments**
+
+-   `lon` — Longitude. [Float64](../../../sql-reference/data-types/float.md).
+-   `lat` — Latitude. [Float64](../../../sql-reference/data-types/float.md).
+
+**Returned values**
+
+-   S2 point index.
+
+Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
+
+**Example**
+
+Query:
+
+``` sql
+SELECT geoToS2(37.79506683, 55.71290588) as s2Index;
+```
+
+Result:
+
+``` text
+┌─────────────s2Index─┐
+│ 4704772434919038107 │
+└─────────────────────┘
+```
+
+## s2ToGeo {#s2ToGeo}
+
+Returns geo coordinates `(longitude, latitude)` corresponding to the provided [S2](#s2index) point index.
+
+**Syntax**
+
+``` sql
+s2ToGeo(s2index)
+```
+
+**Arguments**
+
+-   `s2Index` — S2 Index. [UInt64](../../../sql-reference/data-types/int-uint.md).
+
+**Returned values**
+
+-   A tuple consisting of two values: `tuple(lon,lat)`.
+
+Type: `lon` - [Float64](../../../sql-reference/data-types/float.md). `lat` — [Float64](../../../sql-reference/data-types/float.md).
+
+
+**Example**
+
+Query:
+
+``` sql
+SELECT s2ToGeo(4704772434919038107) as s2Coodrinates;
+```
+
+Result:
+
+``` text
+┌─s2Coodrinates────────────────────────┐
+│ (37.79506681471008,55.7129059052841) │
+└──────────────────────────────────────┘
+```
+
+
+
+## s2GetNeighbors {#s2GetNeighbors}
+
+Returns S2 neighbor indices corresponding to the provided [S2](#s2index)). Each cell in the S2 system is a quadrilateral bounded by four geodesics. So, each cell has 4 neighbors. 
+
+**Syntax**
+
+``` sql
+s2ToGeo(s2index)
+```
+
+**Arguments**
+
+-   `s2Index` — S2 Index. [UInt64](../../../sql-reference/data-types/int-uint.md).
+
+**Returned values**
+
+-   An array consisting of the 4 neighbor indices: `array[s2index1, s2index3, s2index2, s2index4]`. 
+
+Type: Each S2 index is  [UInt64](../../../sql-reference/data-types/int-uint.md).
+
+
+**Example**
+
+Query:
+
+``` sql
+ select  s2GetNeighbors(5074766849661468672) AS s2Neighbors;
+```
+
+Result:
+
+``` text
+┌─s2Neighbors───────────────────────────────────────────────────────────────────────┐
+│ [5074766987100422144,5074766712222515200,5074767536856236032,5074767261978329088] │
+└───────────────────────────────────────────────────────────────────────────────────┘
+```