diff --git a/docs/en/sql-reference/functions/geo/s2.md b/docs/en/sql-reference/functions/geo/s2.md new file mode 100644 index 00000000000..ebe4cd66d8a --- /dev/null +++ b/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] │ +└───────────────────────────────────────────────────────────────────────────────────┘ +```