# 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-snowflake/key-concepts/spatial-indexes#h3) of this documentation.
## H3\_BOUNDARY
```sql
H3_BOUNDARY(index)
```
**Description**
Returns a geography representing the H3 cell. It will return `null` on error (invalid input).
**Input parameters**
* `index`: `STRING` The H3 cell index as hexadecimal.
**Return type**
`GEOGRAPHY`
**Example**
```sql
SELECT CARTO.CARTO.H3_BOUNDARY('84390cbffffffff');
-- { "coordinates": [ [ [ -3.5769274353957314, 40.613438595935165 ], [ -3.85975632308016, 40.525472355369885 ], ...
```
## H3\_CENTER
```sql
H3_CENTER(index)
```
**Description**
Returns the center of the H3 cell as a GEOGRAPHY point. It will return `null` on error (invalid input).
**Input parameters**
* `index`: `STRING` The H3 cell index.
**Return type**
`GEOGRAPHY`
**Example**
```sql
SELECT CARTO.CARTO.H3_CENTER('84390cbffffffff');
-- { "coordinates": [ -3.6176032466282892, 40.37254058216577 ], "type": "Point" }
```
## H3\_COMPACT
```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`: `ARRAY` of H3 cell indices of the same resolution as hexadecimal.
**Return type**
`ARRAY`
**Example**
```sql
SELECT CARTO.CARTO.H3_COMPACT(ARRAY_CONSTRUCT('85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff', '85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff'));
-- 84390cbffffffff
```
## H3\_DISTANCE
```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`: `STRING` The H3 cell index as hexadecimal.
* `destination`: `STRING` The H3 cell index as hexadecimal.
**Return type**
`BIGINT`
**Example**
```sql
SELECT CARTO.CARTO.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
```
{% hint style="info" %}
**tip**
If you want the distance in meters use [ST\_DISTANCE](https://docs.snowflake.com/en/sql-reference/functions/st_distance.html) between the cells ([H3\_BOUNDARY](#h3_boundary)) or their centroid.
{% endhint %}
## H3\_FROMGEOGPOINT
```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`: `GEOGRAPHY` 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**
`STRING`
**Example**
```sql
SELECT CARTO.CARTO.H3_FROMGEOGPOINT(ST_POINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
```
{% hint style="info" %}
**tip**
If you want the cells covered by a POLYGON see [H3\_POLYFILL](#h3_polyfill).
{% endhint %}
## H3\_FROMLONGLAT
```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` horizontal coordinate of the map.
* `latitude`: `DOUBLE` 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**
`STRING`
**Example**
```sql
SELECT CARTO.CARTO.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
```
## H3\_HEXRING
```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`: `STRING` H3 cell index of the origin.
* `size`: `INT` size of the ring (distance from the origin).
**Return type**
`ARRAY`
**Example**
```sql
SELECT CARTO.CARTO.H3_HEXRING('84390cbffffffff', 1);
-- 84392b5ffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
```
## H3\_INT\_TOSTRING
```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**
`STRING`
**Example**
```sql
SELECT CARTO.CARTO.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
```
## H3\_ISPENTAGON
```sql
H3_ISPENTAGON(index)
```
**Description**
Returns `true` if given H3 index is a pentagon. Returns `false` otherwise, even on invalid input.
**Input parameters**
* `index`: `STRING` The H3 cell index as hexadecimal.
**Return type**
`BOOLEAN`
**Examples**
```sql
SELECT CARTO.CARTO.H3_ISPENTAGON('84390cbffffffff');
-- FALSE
```
```sql
SELECT CARTO.CARTO.H3_ISPENTAGON('8075fffffffffff');
-- TRUE
```
## H3\_ISVALID
```sql
H3_ISVALID(index)
```
**Description**
Returns `true` when the given index is valid, `false` otherwise.
**Input parameters**
* `index`: `STRING` The H3 cell index as hexadecimal.
**Return type**
`BOOLEAN`
**Examples**
```sql
SELECT CARTO.CARTO.H3_ISVALID('84390cbffffffff');
-- TRUE
```
```sql
SELECT CARTO.CARTO.H3_ISVALID('1');
-- FALSE
```
## H3\_KRING
```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`: `STRING` H3 cell index of the origin.
* `size`: `INT` size of the ring (distance from the origin).
**Return type**
`ARRAY`
**Example**
```sql
SELECT CARTO.CARTO.H3_KRING('84390cbffffffff', 1);
-- 84390cbffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
-- 84392b5ffffffff
```
## H3\_KRING\_DISTANCES
```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`: `STRING` H3 cell index of the origin.
* `size`: `INT` size of the ring (distance from the origin).
**Return type**
`ARRAY`
**Example**
```sql
SELECT CARTO.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}
```
## H3\_POLYFILL
```sql
H3_POLYFILL(geography, resolution [, mode])
```
**Description**
Returns an array with all H3 cell indexes contained in the given polygon. There are three modes which decide if a H3 cell is contained in the polygon:
**Input parameters**
* `geography`: `GEOGRAPHY` **polygon** or **multipolygon** representing the shape to cover. **GeometryCollections** are also allowed but they should contain **polygon** or **multipolygon** geographies. Non-Polygon types will not raise an error but will be ignored instead.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).
* `mode`: `STRING` ``. Optional. Defaults to 'center' mode.
* `center`: The center point of the H3 cell must be within the polygon.
* `contains`: The H3 cell must be fully contained within the polygon (least inclusive).
* `intersects`: The H3 cell intersects in any way with the polygon (most inclusive).
Mode `center`:
Mode `intersects`:
Mode `contains`:
**Return type**
`ARRAY`
**Examples**
```sql
SELECT CARTO.CARTO.H3_POLYFILL(
TO_GEOGRAPHY('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'), 4);
-- 842da29ffffffff
-- 843f725ffffffff
-- 843eac1ffffffff
-- 8453945ffffffff
-- ...
```
```sql
SELECT CARTO.CARTO.H3_POLYFILL(
TO_GEOGRAPHY('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'), 4, 'center');
-- 842da29ffffffff
-- 843f725ffffffff
-- 843eac1ffffffff
-- 8453945ffffffff
-- ...
```
```sql
SELECT CARTO.CARTO.H3_POLYFILL(
TO_GEOGRAPHY('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'), 4, 'contains');
-- 843f0cbffffffff
-- 842da01ffffffff
-- 843e467ffffffff
-- 843ea99ffffffff
-- 843f0c3ffffffff
-- ...
```
```sql
SELECT CARTO.CARTO.H3_POLYFILL(
TO_GEOGRAPHY('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'), 4, 'intersects');
-- 843f0cbffffffff
-- 842da01ffffffff
-- 843e467ffffffff
-- 843ea99ffffffff
-- 843f0c3ffffffff
-- 843ea91ffffffff
-- ...
```
## H3\_POLYFILL\_TABLE (BETA)
```sql
H3_POLYFILL_TABLE(input_query, resolution, mode, output_table)
```
**Description**
Returns a table with the H3 cell indexes contained in the given polygon at a requested resolution. Containment is determined by the mode: center, intersects, contains. All the attributes except the polygon will be included in the output table, clustered by the h3 column.
**Input parameters**
* `input_query`: `STRING` input data to polyfill. It must contain a column `geom` with the shape to cover. Additionally, other columns can be included.
* `resolution`: `INT` number between 0 and 15 with the [H3 resolution](https://h3geo.org/docs/core-library/restable).
* `mode`: `STRING` ``. Optional. Defaults to 'center' mode.
* `center`: The center point of the H3 cell must be within the polygon.
* `contains`: The H3 cell must be fully contained within the polygon (least inclusive).
* `intersects`: The H3 cell intersects in any way with the polygon (most inclusive).
Mode `center`:
Mode `intersects`:
Mode `contains`:
**Output**
The results are stored in the table named ``, which contains the following columns:
* `h3`: `STRING` the geometry of the considered point.
* The rest of columns included in `input_query` except `geom`.
**Examples**
```sql
CALL CARTO.CARTO.H3_POLYFILL_TABLE(
'SELECT TO_GEOGRAPHY(''POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'') AS geom',
9, 'intersects',
'..'
);
-- The table `..` will be created
-- with column: h3
```
```sql
CALL CARTO.CARTO.H3_POLYFILL_TABLE(
'SELECT geom, name, value FROM ..',
9, 'center',
'..'
);
-- The table `..` will be created
-- with columns: h3, name, value
```
## H3\_RESOLUTION
```sql
H3_RESOLUTION(index)
```
**Description**
Returns the H3 cell resolution as an integer. It will return `null` on error (invalid input).
**Input parameters**
* `index`: `STRING` The H3 cell index.
**Return type**
`INT`
**Example**
```sql
SELECT CARTO.CARTO.H3_RESOLUTION('84390cbffffffff');
-- 4
```
## H3\_STRING\_TOINT
```sql
H3_STRING_TOINT(index)
```
**Description**
Converts the string representation of the H3 index to the integer representation.
**Input parameters**
* `index`: `STRING` The H3 cell index.
**Return type**
`INT`
**Example**
```sql
SELECT CARTO.CARTO.H3_STRING_TOINT('84390cbffffffff');
-- 595478781590765567
```
## H3\_TOCHILDREN
```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`: `STRING` 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**
`ARRAY`
**Example**
```sql
SELECT CARTO.CARTO.H3_TOCHILDREN('83390cfffffffff', 4);
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390c5ffffffff
-- 84390c7ffffffff
-- 84390c9ffffffff
-- 84390cbffffffff
-- 84390cdffffffff
```
## H3\_TOPARENT
```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`: `STRING` 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**
`STRING`
**Example**
```sql
SELECT CARTO.CARTO.H3_TOPARENT('84390cbffffffff', 3);
-- 83390cfffffffff
```
## H3\_UNCOMPACT
```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`: `ARRAY` 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**
`ARRAY`
**Example**
```sql
SELECT CARTO.CARTO.H3_UNCOMPACT(ARRAY_CONSTRUCT('84390cbffffffff'), 5);
-- 85390ca3fffffff
-- 85390ca7fffffff
-- 85390cabfffffff
-- 85390caffffffff
-- 85390cb3fffffff
-- 85390cb7fffffff
-- 85390cbbfffffff
```
