quadbin

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

QUADBIN_FROMLONGLAT

QUADBIN_FROMLONGLAT(longitude, latitude, resolution)

Description

Returns the Quadbin representation of a point for a requested resolution and geographic coordinates.

Input parameters

• longitude: DOUBLE longitude (WGS84) of the point.

• latitude: DOUBLE latitude (WGS84) of the point.

• resolution: INT level of detail or zoom.

Return type

BIGINT

Example

SELECT carto.QUADBIN_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 5207251884775047167

QUADBIN_FROMGEOGPOINT

QUADBIN_FROMGEOGPOINT(point, resolution)

Description

Returns the Quadbin of a given point at a requested resolution.

Input parameters

• point: GEOMETRY(4326) geographic point.

• resolution: INT level of detail or zoom.

Return type

BIGINT

Example

SELECT carto.QUADBIN_FROMGEOGPOINT(ST_POINT(-3.7038, 40.4168, 4326), 4);
-- 5207251884775047167

QUADBIN_FROMZXY

QUADBIN_FROMZXY(z, x, y)

Description

Returns a Quadbin from z, x, y tile coordinates.

Input parameters

• z: INT zoom level.

• x: INT horizontal position of a tile.

• y: INT vertical position of a tile.

Constraints

Tile coordinates x and y depend on the zoom level z. For both coordinates, the minimum value is 0, and the maximum value is two to the power of z, minus one (2^z - 1).

Return type

BIGINT

Example

SELECT carto.QUADBIN_FROMZXY(4, 7, 6);
-- 5207251884775047167

QUADBIN_FROMQUADKEY

QUADBIN_FROMQUADKEY(quadkey)

Description

Compute a quadbin index from a quadkey.

Input parameters

• quadkey: STRING Quadkey representation of the index.

Return type

BIGINT

Example

SELECT carto.QUADBIN_FROMQUADKEY('0331110121');
-- 5234261499580514303

QUADBIN_TOPARENT

QUADBIN_TOPARENT(quadbin, resolution)

Description

Returns the parent (ancestor) Quadbin of a given Quadbin for a specific resolution. An ancestor of a given Quadbin is a Quadbin of smaller resolution that spatially contains it.

Input parameters

• quadbin: BIGINT Quadbin to get the parent from.

• resolution: INT resolution of the desired parent.

Return type

BIGINT

Example

SELECT carto.QUADBIN_TOPARENT(5207251884775047167, 3);
-- 5202783469519765503

QUADBIN_TOCHILDREN

QUADBIN_TOCHILDREN(quadbin, resolution)

Description

Returns an array with the children Quadbins of a given Quadbin for a specific resolution. A children Quadbin is a Quadbin of higher level of detail that is contained by the current Quadbin. Each Quadbin has four direct children (at the next higher resolution).

Input parameters

• quadbin: BIGINT Quadbin to get the children from.

• resolution: INT resolution of the desired children.

Return type

ARRAY<BIGINT>

Example

SELECT carto.QUADBIN_TOCHILDREN(5207251884775047167, 5);
-- [5211742290262884351, 5211751086355906559,
--  5211746688309395455, 5211755484402417663]

QUADBIN_TOQUADKEY

QUADBIN_TOQUADKEY(quadbin)

Description

Compute a quadkey from a quadbin index.

Input parameters

• quadbin: BIGINT Quadbin index.

Return type

STRING

Example

SELECT carto.QUADBIN_TOQUADKEY(5234261499580514303);
-- '0331110121'

QUADBIN_TOZXY

QUADBIN_TOZXY(quadbin)

Description

Returns the zoom level z and coordinates x, y for a given Quadbin.

Input parameters

• quadbin: BIGINT Quadbin from which to obtain the coordinates.

Return type

STRUCT<z: INT, x: INT, y: INT>

Example

SELECT carto.QUADBIN_TOZXY(5207251884775047167);
-- {"z": 4, "x": 7, "y": 6}

QUADBIN_RESOLUTION

QUADBIN_RESOLUTION(quadbin)

Description

Returns the resolution of the input Quadbin.

Input parameters

• quadbin: BIGINT Quadbin from which to get the resolution.

Return type

INT

Example

SELECT carto.QUADBIN_RESOLUTION(5207251884775047167);
-- 4

QUADBIN_ISVALID

QUADBIN_ISVALID(quadbin)

Description

Returns true when the given index is a valid Quadbin, false otherwise.

Input parameters

• quadbin: BIGINT Quadbin index.

Return type

BOOLEAN

Examples

SELECT carto.QUADBIN_ISVALID(5207251884775047167);
-- TRUE

SELECT carto.QUADBIN_ISVALID(1234);
-- FALSE

QUADBIN_KRING

QUADBIN_KRING(origin, size)

Description

Returns all cell indexes in a filled square k-ring centered at the origin in no particular order.

Input parameters

• origin: BIGINT Quadbin index of the origin.

• size: INT size of the ring (distance from the origin).

Return type

ARRAY<BIGINT>

Example

SELECT carto.QUADBIN_KRING(5207251884775047167, 1);
-- [5207128739472736255, 5207234292589002751,
--  5207269476961091583, 5207146331658780671,
--  5207251884775047167, 5207287069147135999,
--  5207902795658690559, 5208008348774957055,
--  5208043533147045887]

QUADBIN_KRING_DISTANCES

QUADBIN_KRING_DISTANCES(origin, size)

Description

Returns all cell indexes and their distances in a filled square k-ring centered at the origin in no particular order.

Input parameters

• origin: BIGINT Quadbin index of the origin.

• size: INT size of the ring (distance from the origin).

Return type

ARRAY<STRUCT<index: BIGINT, distance: INT>>

Example

SELECT carto.QUADBIN_KRING_DISTANCES(5207251884775047167, 1);
-- [{"index": 5207128739472736255, "distance": 1},
--  {"index": 5207234292589002751, "distance": 1},
--  ...
--  {"index": 5207251884775047167, "distance": 0},
--  ...]

**tip**

The distance of the rings is computed as the [Chebyshev distance](https://en.wikipedia.org/wiki/Chebyshev_distance).

QUADBIN_BBOX

QUADBIN_BBOX(quadbin)

Description

Returns an array with the boundary box of a given Quadbin. This boundary box contains the minimum and maximum longitude and latitude. The output format is [West, South, East, North] or [min long, min lat, max long, max lat].

Input parameters

• quadbin: BIGINT Quadbin to get the bbox from.

Return type

ARRAY<DOUBLE>

Example

SELECT carto.QUADBIN_BBOX(5207251884775047167);
-- [-22.5, 21.943045533438166, 0.0, 40.97989806962013]

QUADBIN_CENTER

QUADBIN_CENTER(quadbin)

Description

Returns the center of a given Quadbin as a GEOMETRY(4326) POINT. The center is the intersection point of the four immediate children Quadbin.

Input parameters

• quadbin: BIGINT Quadbin to get the center from.

Return type

GEOMETRY(4326)

Example

SELECT ST_ASTEXT(carto.QUADBIN_CENTER(5207251884775047167));
-- POINT(-11.25 31.952162238024955)

QUADBIN_BOUNDARY

QUADBIN_BOUNDARY(quadbin)

Description

Returns the boundary for a given Quadbin as a GEOMETRY(4326) POLYGON with the same coordinates as given by the QUADBIN_BBOX function.

Input parameters

• quadbin: BIGINT Quadbin to get the boundary from.

Return type

GEOMETRY(4326)

Example

SELECT ST_ASTEXT(carto.QUADBIN_BOUNDARY(5207251884775047167));
-- POLYGON((-22.5 21.9430455334,-22.5 40.9798980696,0.0 40.9798980696,0.0 21.9430455334,-22.5 21.9430455334))

QUADBIN_DISTANCE

QUADBIN_DISTANCE(origin, destination)

Description

Returns the Chebyshev distance between two quadbin indexes. The origin and destination indices must have the same resolution. Otherwise NULL will be returned.

Input parameters

• origin: BIGINT origin quadbin index.

• destination: BIGINT destination quadbin index.

Return type

BIGINT

Example

SELECT carto.QUADBIN_DISTANCE(5207251884775047167, 5207128739472736255);
-- 1

QUADBIN_SIBLING

QUADBIN_SIBLING(quadbin, direction)

Description

Returns the Quadbin directly next to the given Quadbin at the same resolution. The direction must be set in the corresponding argument and currently only horizontal/vertical neighbours are supported. It will return NULL if the sibling does not exist.

Input parameters

• quadbin: BIGINT Quadbin to get the sibling from.

• direction: STRING 'right'|'left'|'up'|'down' direction to move in to extract the next sibling.

Return type

BIGINT

Example

SELECT carto.QUADBIN_SIBLING(5207251884775047167, 'up');
-- 5207146331658780671

QUADBIN_POLYFILL

QUADBIN_POLYFILL(geom, resolution)

Description

Returns an array of Quadbins that intersect with the given geometry at a requested resolution.

Input parameters

• geom: GEOMETRY(4326) geometry to extract the Quadbins from.

• resolution: INT level of detail or zoom.

Return type

ARRAY<BIGINT>

Example

SELECT carto.QUADBIN_POLYFILL(
    ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))', 4326),
    17
);
-- [5265786693153193983, 5265786693163941887,
--  5265786693164466175, 5265786693164204031,
--  5265786693164728319, 5265786693165514751]