# s2

Our S2 module is based on a port of the official S2 geometry library created by Google. For more information about S2 check the [library's website](http://s2geometry.io/) or the [Spatial Indexes section](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-bigquery/key-concepts/spatial-indexes#s2) of this documentation.

## S2\_BOUNDARY <a href="#s2_boundary" id="s2_boundary"></a>

```sql
S2_BOUNDARY(id)
```

**Description**

Returns the boundary for a given S2 cell ID. We extract the boundary by getting the corner longitudes and latitudes, then enclose it in a GeoJSON and finally transform it into geography.

**Input parameters**

* `id`: `INT64` S2 cell ID to get the boundary geography from.

**Return type**

`GEOGRAPHY`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_BOUNDARY(955378847514099712);
-- POLYGON((-3.41955272426037 40.25850071217, -3.41955272426037  ...
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_BOUNDARY(955378847514099712);
-- POLYGON((-3.41955272426037 40.25850071217, -3.41955272426037  ...
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_BOUNDARY(955378847514099712);
-- POLYGON((-3.41955272426037 40.25850071217, -3.41955272426037  ...
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
S2 Cell edges are spherical geodesics. The boundary edges can be interpreted as straight lines in other GIS tools, so to export the exact shape of the cells, use `ST_GEOGFROM(ST_ASGEOJSON(geog)`. In this process, BigQuery will add intermediate points to preserve the geodesic curves.
{% endhint %}

## S2\_CENTER <a href="#s2_center" id="s2_center"></a>

```sql
S2_CENTER(id)
```

**Description**

Returns a POINT corresponding to the centroid of an S2 cell, given its ID.

**Input parameters**

* `id`: `INT64` S2 cell ID to get the boundary geography from.

**Return type**

`GEOGRAPHY`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_CENTER(955378847514099712);
-- POINT(-3.58126923539589 40.4167087628243)
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_CENTER(955378847514099712);
-- POINT(-3.58126923539589 40.4167087628243)
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_CENTER(955378847514099712);
-- POINT(-3.58126923539589 40.4167087628243)
```

{% endtab %}
{% endtabs %}

## S2\_FROMGEOGPOINT <a href="#s2_fromgeogpoint" id="s2_fromgeogpoint"></a>

```sql
S2_FROMGEOGPOINT(point, resolution)
```

**Description**

Returns the S2 cell ID of a given point at a requested resolution.

**Input parameters**

* `point`: `GEOGRAPHY` point to get the ID from.
* `resolution`: `INT64` level of detail or zoom.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 8);
-- 955378847514099712
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 8);
-- 955378847514099712
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 8);
-- 955378847514099712
```

{% endtab %}
{% endtabs %}

## S2\_FROMHILBERTQUADKEY <a href="#s2_fromhilbertquadkey" id="s2_fromhilbertquadkey"></a>

```sql
S2_FROMHILBERTQUADKEY(hquadkey)
```

**Description**

Returns the conversion of a Hilbert quadkey (a.k.a Hilbert curve quadtree ID) into a S2 cell ID.

**Input parameters**

* `hquadkey`: `STRING` Hilbert quadkey to be converted.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_FROMHILBERTQUADKEY('0/12220101');
-- 955378847514099712
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_FROMHILBERTQUADKEY('0/12220101');
-- 955378847514099712
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_FROMHILBERTQUADKEY('0/12220101');
-- 955378847514099712
```

{% endtab %}
{% endtabs %}

## S2\_FROMLONGLAT <a href="#s2_fromlonglat" id="s2_fromlonglat"></a>

```sql
S2_FROMLONGLAT(longitude, latitude, resolution)
```

**Description**

Returns the S2 cell ID for a given longitude, latitude and zoom resolution.

**Input parameters**

* `longitude`: `FLOAT64` horizontal coordinate on the map.
* `latitude`: `FLOAT64` vertical coordinate on the map.
* `resolution`: `INT64` level of detail or zoom.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_FROMLONGLAT(-3.7038, 40.4168, 8);
-- 955378847514099712
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_FROMLONGLAT(-3.7038, 40.4168, 8);
-- 955378847514099712
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_FROMLONGLAT(-3.7038, 40.4168, 8);
-- 955378847514099712
```

{% endtab %}
{% endtabs %}

## S2\_FROMTOKEN <a href="#s2_fromtoken" id="s2_fromtoken"></a>

```sql
S2_FROMTOKEN(token)
```

**Description**

Returns the conversion of a token into a S2 cell ID.

**Input parameters**

* `token`: `STRING` S2 cell hexified ID.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_FROMTOKEN('0d423');
-- 955378847514099712
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_FROMTOKEN('0d423');
-- 955378847514099712
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_FROMTOKEN('0d423');
-- 955378847514099712
```

{% endtab %}
{% endtabs %}

## S2\_FROMUINT64REPR <a href="#s2_fromuint64repr" id="s2_fromuint64repr"></a>

```sql
S2_FROMUINT64REPR(uid)
```

**Description**

Returns the cell ID from a UINT64 representation.

**Input parameters**

* `uid`: `STRING` UINT64 representation of a S2 cell ID.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_FROMUINT64REPR('9926595690882924544');
-- -8520148382826627072
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_FROMUINT64REPR('9926595690882924544');
-- -8520148382826627072
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_FROMUINT64REPR('9926595690882924544');
-- -8520148382826627072
```

{% endtab %}
{% endtabs %}

## S2\_RESOLUTION <a href="#s2_resolution" id="s2_resolution"></a>

```sql
S2_RESOLUTION(index)
```

**Description**

Returns the S2 cell resolution as an integer.

**Input parameters**

* `index`: `STRING` The S2 cell index.

**Return type**

`INT64`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_RESOLUTION(955378847514099712);
-- 9
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_RESOLUTION(955378847514099712);
-- 9
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_RESOLUTION(955378847514099712);
-- 9
```

{% endtab %}
{% endtabs %}

## S2\_TOCHILDREN <a href="#s2_tochildren" id="s2_tochildren"></a>

```sql
S2_TOCHILDREN(index, resolution)
```

**Description**

Returns an array with the S2 indexes of the children/descendents of the given hexagon at the given resolution.

**Input parameters**

* `index`: `STRING` The S2 cell index.
* `resolution`: `INT64` number between 0 and 30 with the [S2 resolution](https://s2geo.org/docs/core-library/restable).

**Return type**

`ARRAY<STRING>`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_TOCHILDREN(955378847514099712, 10);
-- 955365653374566400
-- 955374449467588608
-- 955383245560610816
-- 955392041653633024
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_TOCHILDREN(955378847514099712, 10);
-- 955365653374566400
-- 955374449467588608
-- 955383245560610816
-- 955392041653633024
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_TOCHILDREN(955378847514099712, 10);
-- 955365653374566400
-- 955374449467588608
-- 955383245560610816
-- 955392041653633024
```

{% endtab %}
{% endtabs %}

## S2\_TOHILBERTQUADKEY <a href="#s2_tohilbertquadkey" id="s2_tohilbertquadkey"></a>

```sql
S2_TOHILBERTQUADKEY(id)
```

**Description**

Returns the conversion of a S2 cell ID into a Hilbert quadkey (a.k.a Hilbert curve quadtree ID).

**Input parameters**

* `id`: `INT64` S2 cell ID to be converted.

**Return type**

`STRING`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_TOHILBERTQUADKEY(955378847514099712);
-- 0/12220101
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_TOHILBERTQUADKEY(955378847514099712);
-- 0/12220101
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_TOHILBERTQUADKEY(955378847514099712);
-- 0/12220101
```

{% endtab %}
{% endtabs %}

## S2\_TOTOKEN <a href="#s2_totoken" id="s2_totoken"></a>

```sql
S2_TOTOKEN(id)
```

**Description**

Returns the conversion of a S2 cell ID into a token (S2 cell hexified ID).

**Input parameters**

* `id`: `INT64` S2 cell ID.

**Return type**

`STRING`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_TOTOKEN(955378847514099712);
-- 0d423
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_TOTOKEN(955378847514099712);
-- 0d423
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_TOTOKEN(955378847514099712);
-- 0d423
```

{% endtab %}
{% endtabs %}

## S2\_TOUINT64REPR <a href="#s2_touint64repr" id="s2_touint64repr"></a>

```sql
S2_TOUINT64REPR(id)
```

**Description**

Returns the UINT64 representation of a cell ID.

**Input parameters**

* `id`: `INT64` S2 cell ID.

**Return type**

`STRING`

**Example**

{% tabs %}
{% tab title="carto-un" %}

```sql
SELECT `carto-un`.carto.S2_TOUINT64REPR(-8520148382826627072);
-- 9926595690882924544
```

{% endtab %}

{% tab title="carto-un-eu" %}

```sql
SELECT `carto-un-eu`.carto.S2_TOUINT64REPR(-8520148382826627072);
-- 9926595690882924544
```

{% endtab %}

{% tab title="manual" %}

```sql
SELECT carto.S2_TOUINT64REPR(-8520148382826627072);
-- 9926595690882924544
```

{% endtab %}
{% endtabs %}

<img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-1c82685e4e434438152a8e3d867df996413489fe%2Feu-flag-website.png?alt=media&#x26;token=4343f6e5-973a-4e9a-8e14-50366a086f72" alt="EU flag" data-size="line">This project has received funding from the [European Union’s Horizon 2020](https://ec.europa.eu/programmes/horizon2020/en) research and innovation programme under grant agreement No 960401.