h3

H3 is Uber’s Hexagonal Hierarchical Spatial Index. Full documentation of the project can be found at h3geo. You can also learn more about H3 in the Spatial Indexes section of this documentation.

H3_BOUNDARY

H3_BOUNDARY(index)

Description

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

• index: STRING The H3 cell index.

Return type

GEOGRAPHY

Example

carto-un

SELECT `carto-un`.carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON((-3.57692743539573 40.6134385959352, -3.85975632308016 ...

carto-un-eu

manual

Additional examples

• An H3 grid of Starbucks locations and simple cannibalization analysis

H3_CENTER

H3_CENTER(index)

Description

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

• index: STRING The H3 cell index.

Return type

GEOGRAPHY

Example

carto-un

SELECT `carto-un`.carto.H3_CENTER('84390cbffffffff');
-- POINT(-3.61760324662829 40.3725405821658)

carto-un-eu

manual

H3_COMPACT

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.

• indexArray: ARRAY<STRING> of H3 cell indices of the same resolution.

Return type

ARRAY<STRING>

Example

carto-un

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

carto-un-eu

manual

H3_DISTANCE

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.

• origin: STRING origin H3 cell index.

• destination: STRING destination H3 cell index.

Return type

INT64

Example

carto-un

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

carto-un-eu

manual

tip

If you want the distance in meters use ST_DISTANCE between the cells (H3_BOUNDARY) or their centroid.

Additional examples

• Opening a new Pizza Hut location in Honolulu

H3_FROMGEOGPOINT

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.

• point: GEOGRAPHY point to get the H3 cell from.

• resolution: INT64 number between 0 and 15 with the H3 resolution.

Return type

STRING

Example

carto-un

SELECT `carto-un`.carto.H3_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff

carto-un-eu

manual

tip

If you want the cells covered by a POLYGON see H3_POLYFILL.

Additional examples

• An H3 grid of Starbucks locations and simple cannibalization analysis

H3_FROMLONGLAT

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).

• longitude: FLOAT64 horizontal coordinate of the map.

• latitude: FLOAT64 vertical coordinate of the map.

• resolution: INT64 number between 0 and 15 with the H3 resolution.

Return type

STRING

Example

carto-un

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

carto-un-eu

manual

H3_HEXRING

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, this function will throw an exception if there is a pentagon anywhere in the ring.

• origin: STRING H3 cell index of the origin.

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

Return type

ARRAY<STRING>

Example

carto-un

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

carto-un-eu

manual

H3_INT_TOSTRING

H3_INT_TOSTRING(index)

Description

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

• index: INT64 The H3 cell index.

Return type

STRING

Example

carto-un

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

carto-un-eu

manual

H3_ISPENTAGON

H3_ISPENTAGON(index)

Description

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

• index: STRING The H3 cell index.

Return type

BOOLEAN

Example

carto-un

SELECT `carto-un`.carto.H3_ISPENTAGON('84390cbffffffff');
-- false

carto-un-eu

manual

carto-un

SELECT `carto-un`.carto.H3_ISPENTAGON('8075fffffffffff');
-- true

carto-un-eu

manual

H3_ISVALID

H3_ISVALID(index)

Description

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

• index: STRING The H3 cell index.

Return type

BOOLEAN

Examples

carto-un

SELECT `carto-un`.carto.H3_ISVALID('84390cbffffffff');
-- true

carto-un-eu

manual

carto-un

SELECT `carto-un`.carto.H3_ISVALID('1');
-- false

carto-un-eu

manual

H3_KRING

H3_KRING(origin, size)

Description

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

• origin: STRING H3 cell index of the origin.

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

Return type

ARRAY<STRING>

Example

carto-un

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

carto-un-eu

manual

Additional examples

• An H3 grid of Starbucks locations and simple cannibalization analysis

H3_KRING_DISTANCES

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.

• origin: STRING H3 cell index of the origin.

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

Return type

ARRAY<STRUCT<index STRING, distance INT64>>

Example

carto-un

SELECT `carto-un`.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"}

carto-un-eu

manual

H3_POLYFILL

H3_POLYFILL(geog, resolution)

Description

Returns an array of H3 cell indexes contained in the given geography (Polygon, MultiPolygon) at a requested resolution. Containment is determined by the cells' center. This function is equivalent to H3_POLYFILL_MODE with mode center.

• geog: GEOGRAPHY representing the shape to cover.

• resolution: INT64 level of detail. The value must be between 0 and 15 (H3 resolution table).

Use H3_POLYFILL_MODE with mode intersects in the following cases:

• You want to provide the minimum covering set of a Polygon, MultiPolygon.

• The input geography type is Point, MultiPoint, LineString, MultiLineString.

Return type

ARRAY<STRING>

Examples

carto-un

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

carto-un-eu

manual

carto-un

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

carto-un-eu

manual

carto-un

SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(`carto-un`.carto.H3_POLYFILL(geog, 9)) AS h3;

carto-un-eu

manual

Additional examples

• Opening a new Pizza Hut location in Honolulu

H3_POLYFILL_MODE

H3_POLYFILL_MODE(geog, resolution, mode)

Description

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

• geog: GEOGRAPHY representing the shape to cover.

• resolution: INT64 level of detail. The value must be between 0 and 15 (H3 resolution table).

• mode: STRING

  • center returns the indexes of the H3 cells which centers intersect the input geography (polygon). The resulting H3 set does not fully cover the input geography, however, this is significantly faster that the other modes. This mode is not compatible with points or lines. Equivalent to H3_POLYFILL.

  • intersects returns the indexes of the H3 cells that intersect the input geography. The resulting H3 set will completely cover the input geography (point, line, polygon).

  • contains returns the indexes of the H3 cells that are entirely contained inside the input geography (polygon). This mode is not compatible with points or lines.

Mode center:

Mode intersects:

Mode contains:

Return type

ARRAY<STRING>

Examples

carto-un

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

carto-un-eu

manual

carto-un

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

carto-un-eu

manual

carto-un

SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(`carto-un`.carto.H3_POLYFILL_MODE(geog, 9, 'intersects')) AS h3;

carto-un-eu

manual

H3_POLYFILL_TABLE (BETA)

H3_POLYFILL_TABLE(input_query, resolution, mode, output_table)

Description

Returns a table with the H3 cell indexes contained in the given geography at a requested resolution. Containment is determined by the mode: center, intersects, contains. All the attributes except the geography will be included in the output table, clustered by the h3 column.

• 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: INT64 level of detail. The value must be between 0 and 15 (H3 resolution table).

• mode: STRING

  • center returns the indexes of the H3 cells which centers intersect the input geography (polygon). The resulting H3 set does not fully cover the input geography, however, this is significantly faster that the other modes. This mode is not compatible with points or lines. Equivalent to H3_POLYFILL.

  • intersects returns the indexes of the H3 cells that intersect the input geography. The resulting H3 set will completely cover the input geography (point, line, polygon).

  • contains returns the indexes of the H3 cells that are entirely contained inside the input geography (polygon). This mode is not compatible with points or lines.

• output_table: STRING name of the output table to store the results of the polyfill.

Mode center:

Mode intersects:

Mode contains:

Output

The results are stored in the table named <output_table>, which contains the following columns:

• h3: STRING the geometry of the considered point.

• The rest of columns included in input_query except geom.

Examples

carto-un

CALL `carto-un`.carto.H3_POLYFILL_TABLE(
  "SELECT ST_GEOGFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))') AS geom",
  9, 'intersects',
  '<project>.<dataset>.<output_table>'
);
-- The table `<project>.<dataset>.<output_table>` will be created
-- with column: h3

carto-un-eu

manual

carto-un

CALL `carto-un`.carto.H3_POLYFILL_TABLE(
  'SELECT geom, name, value FROM `<project>.<dataset>.<table>`',
  9, 'center',
  '<project>.<dataset>.<output_table>'
);
-- The table `<project>.<dataset>.<output_table>` will be created
-- with columns: h3, name, value

carto-un-eu

manual

H3_RESOLUTION

H3_RESOLUTION(index)

Description

Returns the H3 cell resolution as an integer. It will return null on error (invalid input).

• index: STRING The H3 cell index.

Return type

INT64

Example

carto-un

SELECT `carto-un`.carto.H3_RESOLUTION('84390cbffffffff');
-- 4

carto-un-eu

manual

H3_STRING_TOINT

H3_STRING_TOINT(index)

Description

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

• index: STRING The H3 cell index.

Return type

INT64

Example

carto-un

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

carto-un-eu

manual

H3_TOCHILDREN

H3_TOCHILDREN(index, resolution)

Description

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

• index: STRING The H3 cell index.

• resolution: INT64 number between 0 and 15 with the H3 resolution.

Return type

ARRAY<STRING>

Example

carto-un

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

carto-un-eu

manual

H3_TOPARENT

H3_TOPARENT(index, resolution)

Description

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

• index: STRING The H3 cell index.

• resolution: INT64 number between 0 and 15 with the H3 resolution.

Return type

STRING

Example

carto-un

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

carto-un-eu

manual

H3_UNCOMPACT

H3_UNCOMPACT(indexArray, resolution)

Description

Returns an array with the H3 indexes of a set of hexagons of the same resolution that represent the same area as the compacted input hexagons.

• indexArray: ARRAY<STRING> of H3 cell indices.

• resolution: INT64 number between 0 and 15 with the H3 resolution.

Return type

ARRAY<STRING>

Example

carto-un

SELECT `carto-un`.carto.H3_UNCOMPACT(['83390cfffffffff'], 5);
-- 85390ca3fffffff
-- 85390ca7fffffff
-- 85390cabfffffff
-- 85390caffffffff
-- 85390cb3fffffff
-- 85390cb7fffffff
-- 85390cbbfffffff

carto-un-eu

manual

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 960401.