# quadbin

You can learn more about Quadbins in the [Spatial Indexes section](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-postgresql/key-concepts/spatial-indexes#quadbin) of the documentation.

## QUADBIN\_BBOX <a href="#quadbin_bbox" id="quadbin_bbox"></a>

```sql
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<FLOAT64>`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_BBOX(5207251884775047167);
-- {-22.5,21.943045533438188,0.0,40.97989806962013}
```

{% endcode %}

## QUADBIN\_BOUNDARY <a href="#quadbin_boundary" id="quadbin_boundary"></a>

```sql
QUADBIN_BOUNDARY(quadbin)
```

**Description**

Returns the boundary for a given Quadbin as a polygon GEOMETRY with the same coordinates as given by the [QUADBIN\_BBOX](#quadbin_bbox) function.

**Input parameters**

* `quadbin`: `BIGINT` Quadbin to get the boundary geometry from.

**Return type**

`GEOGRAPHY`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_BOUNDARY(5207251884775047167);
-- POLYGON ((-22.5 21.943045533438188, -22.5 40.97989806962013, 0 40.97989806962013, 0 21.943045533438188, -22.5 21.943045533438188))
```

{% endcode %}

## QUADBIN\_CENTER <a href="#quadbin_center" id="quadbin_center"></a>

```sql
QUADBIN_CENTER(quadbin)
```

**Description**

Returns the center for a given Quadbin. 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`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_CENTER(5207251884775047167);
-- POINT (-11.25 31.952162238024965)
```

{% endcode %}

## QUADBIN\_DISTANCE <a href="#quadbin_distance" id="quadbin_distance"></a>

```sql
QUADBIN_DISTANCE(origin, destination)
```

**Description**

Returns the [Chebyshev distance](https://en.wikipedia.org/wiki/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**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_FROMGEOGPOINT <a href="#quadbin_fromgeogpoint" id="quadbin_fromgeogpoint"></a>

```sql
QUADBIN_FROMGEOGPOINT(point, resolution)
```

**Description**

Returns the Quadbin of a given point at a requested resolution. This function is an alias for `QUADBIN_FROMGEOPOINT`.

**Input parameters**

* `point`: `GEOMETRY` point to get the Quadbin from.
* `resolution`: `BIGINT` level of detail or zoom.

**Return type**

`BIGINT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_FROMGEOGPOINT(ST_MAKEPOINT(-3.7038, 40.4168), 4);
-- 5207251884775047167
```

{% endcode %}

## QUADBIN\_FROMLONGLAT <a href="#quadbin_fromlonglat" id="quadbin_fromlonglat"></a>

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

**Description**

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

**Input parameters**

* `longitude`: `DOUBLE PRECISION` longitude (WGS84) of the point.
* `latitude`: `DOUBLE PRECISION` latitude (WGS84) of the point.
* `resolution`: `INT` level of detail or zoom.

**Return type**

`BIGINT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_FROMQUADKEY <a href="#quadbin_fromquadkey" id="quadbin_fromquadkey"></a>

```sql
QUADBIN_FROMQUADKEY(quadkey)
```

**Description**

Compute a quadbin index from a quadkey.

**Input parameters**

* `quadkey`: `TEXT` Quadkey representation of the index.

**Return type**

`BIGINT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_FROMZXY <a href="#quadbin_fromzxy" id="quadbin_fromzxy"></a>

```sql
QUADBIN_FROMZXY(z, x, y)
```

**Description**

Returns a Quadbin from `z`, `x`, `y` [tile coordinates](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).

**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**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_ISVALID <a href="#quadbin_isvalid" id="quadbin_isvalid"></a>

```sql
QUADBIN_ISVALID(quadbin)
```

**Description**

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

**Input parameters**

* `quadbin`: `BIGINT` Quadbin index.

**Return type**

`BOOLEAN`

**Examples**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_ISVALID(5207251884775047167);
-- TRUE
```

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_ISVALID(1234);
-- FALSE
```

{% endcode %}

## QUADBIN\_KRING <a href="#quadbin_kring" id="quadbin_kring"></a>

```sql
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**

`BIGINT[]`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_KRING(5207251884775047167, 1);
-- { 5207128739472736255
-- 5207146331658780671
-- 5207234292589002751
-- 5207251884775047167
-- 5207269476961091583
-- 5207287069147135999
-- 5207902795658690559
-- 5208008348774957055
-- 5208043533147045887 }
```

{% endcode %}

## QUADBIN\_KRING\_DISTANCES <a href="#quadbin_kring_distances" id="quadbin_kring_distances"></a>

```sql
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**

`JSON[]`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_KRING_DISTANCES(5207251884775047167, 1);
-- {{"index" : 5207269476961091583, "distance" : "1"}
--  {"index" : 5207251884775047167, "distance" : "0"}
--  {"index" : 5207902795658690559, "distance" : "1"}
--  {"index" : 5208008348774957055, "distance" : "1"}
--  {"index" : 5207234292589002751, "distance" : "1"}
--  {"index" : 5207287069147135999, "distance" : "1"}
--  {"index" : 5207128739472736255, "distance" : "1"}
--  {"index" : 5208043533147045887, "distance" : "1"}
--  {"index" : 5207146331658780671, "distance" : "1"}}
```

{% endcode %}

{% hint style="info" %}
**tip**

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

## QUADBIN\_POLYFILL <a href="#quadbin_polyfill" id="quadbin_polyfill"></a>

```sql
QUADBIN_POLYFILL(geom, resolution [, mode])
```

**Description**

Returns an array of quadbin cell indexes contained in the given geometry at a requested resolution. Containment is determined by the mode: center, intersects, contains.

**Input parameters**

* `geom`: `GEOMETRY` representing the shape to cover.
* `resolution`: `INT` level of detail. The value must be between 0 and 26.
* `mode` (optional): `VARCHAR`
  * `center` (default) returns the indexes of the quadbin cells which centers intersect the input geometry (polygon). The resulting quadbin set does not fully cover the input geometry, however, this is **significantly faster** that the other modes. This mode is not compatible with points or lines.
  * `intersects` returns the indexes of the quadbin cells that intersect the input geometry. The resulting quadbin set will completely cover the input geometry (point, line, polygon).
  * `contains` returns the indexes of the quadbin cells that are entirely contained inside the input geometry (polygon). This mode is not compatible with points or lines.

Mode `center`:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-e0cebef0b9f847b59ca5b64f3a71b1f91b8be48d%2Fquadbin_polyfill_mode_center.png?alt=media&#x26;token=73bac93c-50c4-455e-bb28-15f93010fc90" alt=""><figcaption></figcaption></figure>

Mode `intersects`:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-8ba426b9db031b45fdf103d3168d46d7d2464052%2Fquadbin_polyfill_mode_intersects.png?alt=media&#x26;token=1c968bfc-2622-42dd-a433-0fcfb93bbdf8" alt=""><figcaption></figcaption></figure>

Mode `contains`:

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fgit-blob-534b9d33c1f92dceff1fd1f94b46b44485908ba0%2Fquadbin_polyfill_mode_contains.png?alt=media&#x26;token=e0b6f46e-9d0d-44a1-aee4-86cb0751701f" alt=""><figcaption></figcaption></figure>

**Return type**

`BIGINT[]`

**Examples**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT quadbin
FROM UNNEST(carto.QUADBIN_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  17
)) AS quadbin;
-- 5265786693163941887
-- 5265786693164466175
-- 5265786693164728319
```

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT quadbin
FROM <my-schema>.<my-table>,
  UNNEST(carto.QUADBIN_POLYFILL(geom, 17)) AS quadbin;
```

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT quadbin
FROM UNNEST(carto.QUADBIN_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  17, 'intersects'
)) AS quadbin;
-- 5265786693153193983
-- 5265786693163941887
-- 5265786693164466175
-- 5265786693164204031
-- 5265786693164728319
-- 5265786693165514751
```

{% endcode %}

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT quadbin
FROM <my-schema>.<my-table>,
  UNNEST(carto.QUADBIN_POLYFILL(geom, 17, 'intersects')) AS quadbin;
```

{% endcode %}

## QUADBIN\_RESOLUTION <a href="#quadbin_resolution" id="quadbin_resolution"></a>

```sql
QUADBIN_RESOLUTION(quadbin)
```

**Description**

Returns the resolution of the input Quadbin.

**Input parameters**

* `quadbin`: `BIGINT` Quadbin from which to get the resolution.

**Return type**

`BIGINT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_RESOLUTION(5207251884775047167);
-- 4
```

{% endcode %}

## QUADBIN\_SIBLING <a href="#quadbin_sibling" id="quadbin_sibling"></a>

```sql
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 neigbours are supported. It will return `NULL` if the sibling does not exist.

**Input parameters**

* `quadbin`: `BIGINT` Quadbin to get the sibling from.
* `direction`: `TEXT` `'right'|'left'|'up'|'down'` direction to move in to extract the next sibling.

**Return type**

`BIGINT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_TOCHILDREN <a href="#quadbin_tochildren" id="quadbin_tochildren"></a>

```sql
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**

`BIGINT[]`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

```sql
SELECT carto.QUADBIN_TOCHILDREN(5207251884775047167, 5);
-- { 5211742290262884351
-- 5211751086355906559
-- 5211746688309395455
-- 5211755484402417663 }
```

{% endcode %}

## QUADBIN\_TOPARENT <a href="#quadbin_toparent" id="quadbin_toparent"></a>

```sql
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**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_TOQUADKEY <a href="#quadbin_toquadkey" id="quadbin_toquadkey"></a>

```sql
QUADBIN_TOQUADKEY(quadbin)
```

**Description**

Compute a quadkey from a quadbin index.

**Input parameters**

* `quadbin`: `BIGINT` Quadbin index.

**Return type**

`TEXT`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

## QUADBIN\_TOZXY <a href="#quadbin_tozxy" id="quadbin_tozxy"></a>

```sql
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**

`JSON`

**Example**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}