h3

CORE
​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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON((-3.57692743539573 40.6134385959352, -3.85975632308016 ...
SELECT `carto-un-eu`.carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON((-3.57692743539573 40.6134385959352, -3.85975632308016 ...
SELECT `carto-os`.carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON((-3.57692743539573 40.6134385959352, -3.85975632308016 ...
SELECT carto.H3_BOUNDARY('84390cbffffffff');
-- POLYGON((-3.57692743539573 40.6134385959352, -3.85975632308016 ...
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_CENTER('84390cbffffffff');
-- POINT(-3.61760324662829 40.3725405821658)
SELECT `carto-un-eu`.carto.H3_CENTER('84390cbffffffff');
-- POINT(-3.61760324662829 40.3725405821658)
SELECT `carto-os`.carto.H3_CENTER('84390cbffffffff');
-- POINT(-3.61760324662829 40.3725405821658)
SELECT carto.H3_CENTER('84390cbffffffff');
-- POINT(-3.61760324662829 40.3725405821658)
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_COMPACT(['85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff', '85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff']);
-- 84390cbffffffff
SELECT `carto-un-eu`.carto.H3_COMPACT(['85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff', '85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff']);
-- 84390cbffffffff
SELECT `carto-os`.carto.H3_COMPACT(['85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff', '85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff']);
-- 84390cbffffffff
SELECT carto.H3_COMPACT(['85390ca3fffffff', '85390ca7fffffff', '85390cabfffffff', '85390caffffffff', '85390cb3fffffff', '85390cb7fffffff', '85390cbbfffffff']);
-- 84390cbffffffff
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
SELECT `carto-un-eu`.carto.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
SELECT `carto-os`.carto.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
SELECT carto.H3_DISTANCE('84390c1ffffffff', '84390cbffffffff');
-- 1
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 required resolution. It will return null on error (invalid geography type or resolution out of bounds).
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
SELECT `carto-un-eu`.carto.H3_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
SELECT `carto-os`.carto.H3_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
SELECT carto.H3_FROMGEOGPOINT(ST_GEOGPOINT(-3.7038, 40.4168), 4);
-- 84390cbffffffff
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
SELECT `carto-un-eu`.carto.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
SELECT `carto-os`.carto.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
SELECT carto.H3_FROMLONGLAT(-3.7038, 40.4168, 4);
-- 84390cbffffffff
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_HEXRING('84390cbffffffff', 1);
-- 84392b5ffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
SELECT `carto-un-eu`.carto.H3_HEXRING('84390cbffffffff', 1);
-- 84392b5ffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
SELECT `carto-os`.carto.H3_HEXRING('84390cbffffffff', 1);
-- 84392b5ffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
SELECT carto.H3_HEXRING('84390cbffffffff', 1);
-- 84392b5ffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
SELECT `carto-un-eu`.carto.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
SELECT `carto-os`.carto.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
SELECT carto.H3_INT_TOSTRING(595478781590765567);
-- 84390cbffffffff
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_ISPENTAGON('84390cbffffffff');
-- false
SELECT `carto-un-eu`.carto.H3_ISPENTAGON('84390cbffffffff');
-- false
SELECT `carto-os`.carto.H3_ISPENTAGON('84390cbffffffff');
-- false
SELECT carto.H3_ISPENTAGON('84390cbffffffff');
-- false
carto-un
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_ISPENTAGON('8075fffffffffff');
-- true
SELECT `carto-un-eu`.carto.H3_ISPENTAGON('8075fffffffffff');
-- true
SELECT `carto-os`.carto.H3_ISPENTAGON('8075fffffffffff');
-- true
SELECT carto.H3_ISPENTAGON('8075fffffffffff');
-- true
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_ISVALID('84390cbffffffff');
-- true
SELECT `carto-un-eu`.carto.H3_ISVALID('84390cbffffffff');
-- true
SELECT `carto-os`.carto.H3_ISVALID('84390cbffffffff');
-- true
SELECT carto.H3_ISVALID('84390cbffffffff');
-- true
carto-un
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_ISVALID('1');
-- false
SELECT `carto-un-eu`.carto.H3_ISVALID('1');
-- false
SELECT `carto-os`.carto.H3_ISVALID('1');
-- false
SELECT carto.H3_ISVALID('1');
-- false
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
carto-un-eu
carto-os
manual
SELECT `carto-un`.carto.H3_KRING('84390cbffffffff', 1);
-- 84390cbffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
-- 84392b5ffffffff
SELECT `carto-un-eu`.carto.H3_KRING('84390cbffffffff', 1);
-- 84390cbffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
-- 84392b5ffffffff
SELECT `carto-os`.carto.H3_KRING('84390cbffffffff', 1);
-- 84390cbffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
-- 84392b5ffffffff
SELECT carto.H3_KRING('84390cbffffffff', 1);
-- 84390cbffffffff
-- 84390c9ffffffff
-- 84390c1ffffffff
-- 84390c3ffffffff
-- 84390ddffffffff
-- 84392b7ffffffff
-- 84392b5ffffffff
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
carto-un-eu
carto-os
manual
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"}
SELECT `carto-un-eu`.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"}
SELECT `carto-os`.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"}
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"}
H3_POLYFILL
H3_POLYFILL(geog, resolution)
Description
Returns an array of H3 cell indexes contained in the given geography (Polygon, MultiPolygon) at a given level of detail. 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
carto-un-eu
carto-os
manual
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]
SELECT `carto-un-eu`.carto.H3_POLYFILL(
  ST_GEOGFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9
);
-- [89390cb1b4bffff]
SELECT `carto-os`.carto.H3_POLYFILL(
  ST_GEOGFROMTEXT('POLYGON ((-3.71219873428345 40.413365349070865, -3.7144088745117 40.40965661286395, -3.70659828186035 40.409525904775634, -3.71219873428345 40.413365349070865))'),
  9
);
-- [89390cb1b4bffff]
SELECT 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
carto-un-eu
carto-os
manual
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
SELECT h3
FROM UNNEST(`carto-un-eu`.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
SELECT h3
FROM UNNEST(`carto-os`.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
SELECT h3
FROM UNNEST(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
carto-un-eu
carto-os
manual
SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(`carto-un`.carto.H3_POLYFILL(geog, 9)) AS h3;
SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(`carto-un-eu`.carto.H3_POLYFILL(geog, 9)) AS h3;
SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(`carto-os`.carto.H3_POLYFILL(geog, 9)) AS h3;
SELECT h3
FROM <project>.<dataset>.<table>,
  UNNEST(carto.H3_POLYFILL(geog, 9)) AS h3;
Additional examples
​Opening a new Pizza Hut location in Honolulu​
H3_POLYFILL_MODE
H3_POLYFILL_MODE(geog, resolution, mode)
Description
Returns an array of quadbin cell indexes contained in the given geography at a given level of detail. 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
carto-un-eu
carto-os
manual
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]
SELECT `carto-un-eu`.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]
SELECT `carto-os`.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]
SELECT 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
carto-un-eu
carto-os
manual
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
SELECT h3
FROM UNNEST(`carto-un-eu`.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