# h3

[H3](https://eng.uber.com/h3/) is Uber’s Hexagonal Hierarchical Spatial Index. Full documentation of the project can be found at [h3geo](https://h3geo.org/docs). You can also learn more about H3 in the [Spatial Indexes section](https://docs.carto.com/data-and-analysis/analytics-toolbox-for-postgresql/key-concepts/spatial-indexes#h3) of this documentation.

## H3\_BOUNDARY <a href="#h3_boundary" id="h3_boundary"></a>

```sql
H3_BOUNDARY(index)
```

**Description**

Returns a geography representing the H3 cell. It will return `null` on error (invalid input).

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index as hexadecimal.

**Return type**

`GEOMETRY`

**Example**

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

```sql
SELECT carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON ((-3.5769274353957314 40.613438595935165, -3.85975632308016 40.525472355369885, -3.899552298996668 40.28411330409504, ...
```

{% endcode %}

## H3\_CENTER <a href="#h3_center" id="h3_center"></a>

```sql
H3_CENTER(index)
```

**Description**

Returns the center of the H3 cell as a GEOMETRY point. It will return `null` on error (invalid input).

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index.

**Return type**

`GEOMETRY`

**Example**

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

```sql
SELECT carto.H3_CENTER('84390cbffffffff');
-- POINT (-3.6176032466282892 40.37254058216577)
```

{% endcode %}

## H3\_COMPACT <a href="#h3_compact" id="h3_compact"></a>

```sql
H3_COMPACT(indexArray)
```

**Description**

Returns an array with the indexes of a set of hexagons across multiple resolutions that represent the same area as the input set of hexagons.

**Input parameters**

* `indexArray`: `VARCHAR(16)[]` of H3 cell indices of the same resolution as hexadecimal.

**Return type**

`VARCHAR(16)[]`

**Example**

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

```sql
SELECT carto.H3_COMPACT(ARRAY['85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff','85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff']);
-- { 84390cbffffffff }
```

{% endcode %}

## H3\_DISTANCE <a href="#h3_distance" id="h3_distance"></a>

```sql
H3_DISTANCE(origin, destination)
```

**Description**

Returns the **grid distance** between two hexagon indexes. This function may fail to find the distance between two indexes if they are very far apart or on opposite sides of a pentagon. Returns `null` on failure or invalid input.

**Input parameters**

* `origin`: `VARCHAR(16)` The H3 cell index as hexadecimal.
* `destination`: `VARCHAR(16)` The H3 cell index as hexadecimal.

**Return type**

`BIGINT`

**Example**

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

```sql
SELECT carto.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
```

{% endcode %}

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

If you want the distance in meters use [ST\_DISTANCE](https://postgis.net/docs/ST_Distance.html) between the cells ([H3\_BOUNDARY](#h3_boundary)) or their centroid.
{% endhint %}

## H3\_FROMGEOGPOINT <a href="#h3_fromgeogpoint" id="h3_fromgeogpoint"></a>

```sql
H3_FROMGEOGPOINT(point, resolution)
```

**Description**

Returns the H3 cell index that the point belongs to in the requested `resolution`. It will return `null` on error (invalid geography type or resolution out of bounds). This function is an alias for `H3_FROMGEOPOINT`.

**Input parameters**

* `point`: `GEOMETRY` point to get the H3 cell from.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).

**Return type**

`VARCHAR(16)`

**Example**

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

```sql
SELECT carto.H3_FROMGEOGPOINT(ST_POINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
```

{% endcode %}

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

If you want the cells covered by a POLYGON see [H3\_POLYFILL](#h3_polyfill).
{% endhint %}

## H3\_FROMLONGLAT <a href="#h3_fromlonglat" id="h3_fromlonglat"></a>

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

**Description**

Returns the H3 cell index that the point belongs to in the required `resolution`. It will return `null` on error (resolution out of bounds).

**Input parameters**

* `longitude`: `DOUBLE PRECISION` horizontal coordinate of the map.
* `latitude`: `DOUBLE PRECISION` vertical coordinate of the map.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).

**Return type**

`VARCHAR(16)`

**Example**

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

```sql
SELECT carto.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
```

{% endcode %}

## H3\_HEXRING <a href="#h3_hexring" id="h3_hexring"></a>

```sql
H3_HEXRING(origin, size)
```

**Description**

Returns all cell indexes in a **hollow hexagonal ring** centered at the origin in no particular order. Unlike [H3\_KRING](#h3_kring), this function will throw an exception if there is a pentagon anywhere in the ring.

**Input parameters**

* `origin`: `VARCHAR(16)` H3 cell index of the origin.
* `size`: `INT` size of the ring (distance from the origin).

**Return type**

`VARCHAR(16)[]`

**Example**

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

```sql
SELECT carto.H3_HEXRING('84390cbffffffff', 1);
-- { 84392b5ffffffff,
--   84390c9ffffffff,
--   84390c1ffffffff,
--   84390c3ffffffff,
--   84390ddffffffff,
--   84392b7ffffffff }
```

{% endcode %}

## H3\_INT\_TOSTRING <a href="#h3_int_tostring" id="h3_int_tostring"></a>

```sql
H3_INT_TOSTRING(index)
```

**Description**

Converts the integer representation of the H3 index to the string representation.

**Input parameters**

* `index`: `INT` The H3 cell index.

**Return type**

`VARCHAR(16)`

**Example**

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

```sql
SELECT carto.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
```

{% endcode %}

## H3\_ISPENTAGON <a href="#h3_ispentagon" id="h3_ispentagon"></a>

```sql
H3_ISPENTAGON(index)
```

**Description**

Returns `true` if given H3 index is a pentagon. Returns `false` otherwise, even on invalid input.

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index as hexadecimal.

**Return type**

`BOOLEAN`

**Examples**

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

```sql
SELECT carto.H3_ISPENTAGON('84390cbffffffff');
-- FALSE
```

{% endcode %}

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

```sql
SELECT carto.H3_ISPENTAGON('8075fffffffffff');
-- TRUE
```

{% endcode %}

## H3\_ISVALID <a href="#h3_isvalid" id="h3_isvalid"></a>

```sql
H3_ISVALID(index)
```

**Description**

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

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index as hexadecimal.

**Return type**

`BOOLEAN`

**Examples**

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

```sql
SELECT carto.H3_ISVALID('84390cbffffffff');
-- TRUE
```

{% endcode %}

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

```sql
SELECT carto.H3_ISVALID('1');
-- FALSE
```

{% endcode %}

## H3\_KRING <a href="#h3_kring" id="h3_kring"></a>

```sql
H3_KRING(origin, size)
```

**Description**

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

**Input parameters**

* `origin`: `VARCHAR(16)` H3 cell index of the origin.
* `size`: `INT` size of the ring (distance from the origin).

**Return type**

`VARCHAR(16)[]`

**Example**

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

```sql
SELECT carto.H3_KRING('84390cbffffffff', 1);
-- { 84390cbffffffff,
--   84390c9ffffffff,
--   84390c1ffffffff,
--   84390c3ffffffff,
--   84390ddffffffff,
--   84392b7ffffffff,
--   84392b5ffffffff }
```

{% endcode %}

## H3\_KRING\_DISTANCES <a href="#h3_kring_distances" id="h3_kring_distances"></a>

```sql
H3_KRING_DISTANCES(origin, size)
```

**Description**

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

**Input parameters**

* `origin`: `VARCHAR(16)` H3 cell 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.H3_KRING_DISTANCES('84390cbffffffff', 1);
-- {{"index": "84390cbffffffff", "distance": 0}"
--  {"index": "84390c9ffffffff", "distance": 1}
--  {"index": "84390c1ffffffff", "distance": 1}
--  {"index": "84390c3ffffffff", "distance": 1}
--  {"index": "84390ddffffffff", "distance": 1}
--  {"index": "84392b7ffffffff", "distance": 1}
--  {"index": "84392b5ffffffff", "distance": 1}}
```

{% endcode %}

## H3\_POLYFILL <a href="#h3_polyfill" id="h3_polyfill"></a>

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

**Description**

Returns an array of H3 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 15 ([H3 resolution table](https://h3geo.org/docs/core-library/restable)).
* `mode` (optional): `VARCHAR`
  * `center` (default) returns the indexes of the H3 cells which centers intersect the input geometry (polygon). The resulting H3 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 H3 cells that intersect the input geometry. The resulting H3 set will completely cover the input geometry (point, line, polygon).
  * `contains` returns the indexes of the H3 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-1b47ba3ccecd5a3281889e53f1a0310c457d0997%2Fh3_polyfill_mode_center.png?alt=media" 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-b5b98d05406d730178c9f0abd9cfcaaedfefc634%2Fh3_polyfill_mode_intersects.png?alt=media" 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-aff8edd843d4e19abe187c95890e51236b85221a%2Fh3_polyfill_mode_contains.png?alt=media" alt=""><figcaption></figcaption></figure>

**Return type**

`VARCHAR(16)[]`

**Examples**

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

```sql
SELECT carto.H3_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9
);
-- [89390cb1b4bffff]
```

{% endcode %}

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

```sql
SELECT h3
FROM UNNEST(carto.H3_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9
)) AS h3;
-- 89390cb1b4bffff
```

{% endcode %}

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

```sql
SELECT h3
FROM <my-schema>.<my-table>,
  UNNEST(carto.H3_POLYFILL(geom, 9)) AS h3;
```

{% endcode %}

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

```sql
SELECT carto.H3_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9, 'intersects'
);
-- [89390cb1b4fffff, 89390ca3497ffff, 89390ca34b3ffff, 89390cb1b4bffff, 89390ca3487ffff, 89390cb1b5bffff]
```

{% endcode %}

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

```sql
SELECT h3
FROM UNNEST(carto.H3_POLYFILL(
  ST_GEOMFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9, 'intersects'
)) AS h3;
-- 89390cb1b4fffff
-- 89390ca3497ffff
-- 89390ca34b3ffff
-- 89390cb1b4bffff
-- 89390ca3487ffff
-- 89390cb1b5bffff
```

{% endcode %}

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

```sql
SELECT h3
FROM <my-schema>.<my-table>,
  UNNEST(carto.H3_POLYFILL(geom, 9, 'intersects')) AS h3;
```

{% endcode %}

## H3\_STRING\_TOINT <a href="#h3_string_toint" id="h3_string_toint"></a>

```sql
H3_STRING_TOINT(index)
```

**Description**

Converts the string representation of the H3 index to the integer representation.

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index.

**Return type**

`INT`

**Example**

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

```sql
SELECT carto.H3_STRING_TOINT('84390cbffffffff');
-- 595478781590765567
```

{% endcode %}

## H3\_TOCHILDREN <a href="#h3_tochildren" id="h3_tochildren"></a>

```sql
H3_TOCHILDREN(index, resolution)
```

**Description**

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

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index as hexadecimal.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).

**Return type**

`VARCHAR(16)[]`

**Example**

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

```sql
SELECT carto.H3_TOCHILDREN('83390cfffffffff', 4);
-- { 84390c1ffffffff,
--   84390c3ffffffff,
--   84390c5ffffffff
--   84390c7ffffffff,
--   84390c9ffffffff,
--   84390cbffffffff,
--   84390cdffffffff }
```

{% endcode %}

## H3\_TOPARENT <a href="#h3_toparent" id="h3_toparent"></a>

```sql
H3_TOPARENT(index, resolution)
```

**Description**

Returns the H3 cell index of the parent of the given hexagon at the given resolution.

**Input parameters**

* `index`: `VARCHAR(16)` The H3 cell index as hexadecimal.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).

**Return type**

`VARCHAR`

**Example**

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

```sql
SELECT carto.H3_TOPARENT('84390cbffffffff', 3);
-- 83390cfffffffff
```

{% endcode %}

## H3\_UNCOMPACT <a href="#h3_uncompact" id="h3_uncompact"></a>

```sql
H3_UNCOMPACT(indexArray, resolution)
```

**Description**

Returns an array with the indexes of a set of hexagons of the same `resolution` that represent the same area as the [compacted](#h3_compact) input hexagons.

**Input parameters**

* `indexArray`: `VARCHAR(16)` of H3 cell indices as hexadecimal.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).

**Return type**

`VARCHAR(16)[]`

**Example**

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

```sql
SELECT carto.H3_UNCOMPACT(ARRAY['84390cbffffffff'], 5);
-- { 85390ca3fffffff,
--   85390ca7fffffff,
--   85390cabfffffff,
--   85390caffffffff,
--   85390cb3fffffff,
--   85390cb7fffffff,
--   85390cbbfffffff }
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.carto.com/data-and-analysis/analytics-toolbox-for-postgresql/sql-reference/h3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.