s2

S2 is a library for spherical geometry that aims to have the same robustness, flexibility, and performance as the very best planar geometry libraries.

You can learn more about S2 in the Spatial Indexes section of the documentation.

S2_BOUNDARY

S2_BOUNDARY(id)

Description

Returns the boundary for a given S2 Cell ID as a WKT string. Note that S2 cell vertices should be joined with geodesic edges (great circles), not straight lines in a planar projection.

• id: INT8 id to get the boundary geography from.

Return type

VARCHAR(MAX)

Example

SELECT carto.S2_BOUNDARY(955378847514099712);
-- POLYGON ((-3.74350899127 40.2485011413, -3.41955272426 40.2585007122, -3.41955272426 40.5842313862, -3.74350899127 40.5742134506, -3.74350899127 40.2485011413))

S2_FROMGEOGPOINT

S2_FROMGEOGPOINT(point, resolution)

Description

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

• point: GEOGRAPHY vertical coordinate of the map.

• resolution: INT4 level of detail or zoom.

Return type

INT8

Example

SELECT carto.S2_FROMGEOGPOINT(ST_POINT(-3.7038, 40.4168), 8);
-- 955378847514099712

S2_FROMHILBERTQUADKEY

S2_FROMHILBERTQUADKEY(hquadkey)

Description

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

• hquadkey: VARCHAR(MAX) Hilbert quadkey to be converted.

Return type

INT8

Example

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

S2_FROMLONGLAT

S2_FROMLONGLAT(longitude, latitude, resolution)

Description

Returns the S2 cell ID representation for a requested resolution and geographic coordinates.

• longitude: FLOAT8 horizontal coordinate of the map.

• latitude: FLOAT8 vertical coordinate of the map.

• resolution: INT4 level of detail or zoom.

Return type

INT8

Example

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

S2_FROMTOKEN

S2_FROMTOKEN(token)

Description

Returns the conversion of an S2 cell token (hexified ID) into an unsigned, 64 bit ID.

• token: VARCHAR(MAX) S2 cell token.

Return type

INT8

Example

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

S2_FROMUINT64REPR

S2_FROMUINT64REPR(uid)

Description

Returns an INT64 cell ID from its UINT64 representation.

• uid: VARCHAR(MAX) UINT64 representation of a S2 cell ID.

Return type

INT8

Example

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

S2_POLYFILL_BBOX

S2_POLYFILL_BBOX(min_longitude, max_longitude, min_latitude, max_latitude [, min_resolution, max_resolution])

Description

Returns a SUPER containing an array of S2 cell IDs that cover a planar bounding box. Note that this is a compact coverage (polyfill), so the bounding box is covered with the least amount of cells by using the largest cells possible.

Two optional arguments can be passed with the minimum and maximum resolution for coverage. If you desire a coverage at a single resolution level, simply set the maximum and minimum longitude to be of equal value.

• min_longitude: FLOAT8 minimum longitude of the bounding box.

• max_longitude: FLOAT8 maximum longitude of the bounding box.

• min_latitude: FLOAT8 minimum latitude of the bounding box.

• max_latitude: FLOAT8 maximum latitude of the bounding box.

• min_resolution (optional): INT4 minimum resolution level for cells covering the bounding box. Defaults to 0.

• max_resolution (optional): INT4 maximum resolution level for cells covering the bounding box. Defaults to 30.

Return type

SUPER

Example

SELECT carto.S2_POLYFILL_BBOX(-3.688531, -3.680077, 40.409771, 40.421501);
-- [955367986615549952,955367988763033600,955367994131742720,955368019096240128,
--  955368020975288320,955370721435975680,955370742910812160,955370751500746752]

SELECT carto.S2_POLYFILL_BBOX(-3.688531, -3.680077, 40.409771, 40.421501, 4, 8);
-- [955378847514099712]

-- Single level coverage
SELECT carto.S2_POLYFILL_BBOX(-3.688531, -3.680077, 40.409771, 40.421501, 12, 12);
-- [955367921117298688,955368058556252160,955370669896368128,955370807335321600]

S2_RESOLUTION

S2_RESOLUTION(id)

Description

Returns an integer with the resolution of a given cell ID.

• id: INT8 id to get the resolution from.

Return type

INT4

Example

SELECT carto.S2_RESOLUTION(955378847514099712);
-- 8

S2_TOCHILDREN

S2_TOCHILDREN(id [, resolution])

Description

Returns a SUPER containing a plain array of children IDs of a given cell ID for a specific resolution. A child is an S2 cell of higher level of detail that is contained within the current cell. Each cell has four direct children by definition.

By default, this function returns the direct children (where parent resolution is children resolution - 1). However, an optional resolution argument can be passed with the desired parent resolution. Note that the amount of children grows to the power of four per zoom level.

• id: INT8 id to get the children from.

• resolution (optional): INT4 resolution of the desired children.

Return type

SUPER

Example

SELECT carto.S2_TOCHILDREN(955378847514099712);
-- 955365653374566400
-- 955374449467588608
-- 955383245560610816
-- 955392041653633024

SELECT carto.S2_TOCHILDREN(955378847514099712, 9);
-- 955365653374566400
-- 955374449467588608
-- 955383245560610816
-- 955392041653633024

S2_TOHILBERTQUADKEY

S2_TOHILBERTQUADKEY(id)

Description

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

• id: INT8 S2 cell ID to be converted.

Return type

VARCHAR(MAX)

Example

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

S2_TOPARENT

S2_TOPARENT(id, resolution)

Description

Returns the parent ID of a given cell ID for a specific resolution. A parent cell is the smaller resolution containing cell.

By default, this function returns the direct parent (where parent resolution is child resolution + 1). However, an optional resolution argument can be passed with the desired parent resolution.

• id: INT8 quadint to get the parent from.

• resolution (optional): INT4 resolution of the desired parent.

Return type

INT8

Example

SELECT carto.S2_TOPARENT(955378847514099712);
-- 955396439700144128

SELECT carto.S2_TOPARENT(955378847514099712, 1);
-- 864691128455135232

S2_TOTOKEN

S2_TOTOKEN(id)

Description

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

• id: INT8 S2 cell ID.

Return type

VARCHAR(MAX)

Example

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

S2_TOUINT64REPR

S2_TOUINT64REPR(id)

Description

Returns the UINT64 representation of a cell ID.

• id: INT8 S2 cell ID.

Return type

VARCHAR(MAX)

Example

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