Functions for Working with H3 Indexes
H3 is a geographical indexing system where Earthβs surface divided into a grid of even hexagonal cells. This system is hierarchical, i. e. each hexagon on the top level ("parent") can be splitted into seven even but smaller ones ("children"), and so on.
The level of the hierarchy is called resolution
and can receive a value from 0
till 15
, where 0
is the base
level with the largest and coarsest cells.
A latitude and longitude pair can be transformed to a 64-bit H3 index, identifying a grid cell.
The H3 index is used primarily for bucketing locations and other geospatial manipulations.
The full description of the H3 system is available at the Uber Engeneering site.
h3IsValidβ
Verifies whether the number is a valid H3 index.
Syntax
h3IsValid(h3index)
Parameter
h3index
β Hexagon index number. Type: UInt64.
Returned values
- 1 β The number is a valid H3 index.
- 0 β The number is not a valid H3 index.
Type: UInt8.
Example
Query:
SELECT h3IsValid(630814730351855103) AS h3IsValid;
Result:
ββh3IsValidββ
β 1 β
βββββββββββββ
h3GetResolutionβ
Defines the resolution of the given H3 index.
Syntax
h3GetResolution(h3index)
Parameter
h3index
β Hexagon index number. Type: UInt64.
Returned values
- Index resolution. Range:
[0, 15]
. - If the index is not valid, the function returns a random value. Use h3IsValid to verify the index.
Type: UInt8.
Example
Query:
SELECT h3GetResolution(639821929606596015) AS resolution;
Result:
ββresolutionββ
β 14 β
ββββββββββββββ
h3EdgeAngleβ
Calculates the average length of the H3 hexagon edge in grades.
Syntax
h3EdgeAngle(resolution)
Parameter
resolution
β Index resolution. Type: UInt8. Range:[0, 15]
.
Returned values
Example
Query:
SELECT h3EdgeAngle(10) AS edgeAngle;
Result:
ββββββββh3EdgeAngle(10)ββ
β 0.0005927224846720883 β
βββββββββββββββββββββββββ
h3EdgeLengthMβ
Calculates the average length of the H3 hexagon edge in meters.
Syntax
h3EdgeLengthM(resolution)
Parameter
resolution
β Index resolution. Type: UInt8. Range:[0, 15]
.
Returned values
Example
Query:
SELECT h3EdgeLengthM(15) AS edgeLengthM;
Result:
ββedgeLengthMββ
β 0.509713273 β
βββββββββββββββ
h3EdgeLengthKmβ
Calculates the average length of the H3 hexagon edge in kilometers.
Syntax
h3EdgeLengthKm(resolution)
Parameter
resolution
β Index resolution. Type: UInt8. Range:[0, 15]
.
Returned values
Example
Query:
SELECT h3EdgeLengthKm(15) AS edgeLengthKm;
Result:
ββedgeLengthKmββ
β 0.000509713 β
ββββββββββββββββ
geoToH3β
Returns H3 point index (lon, lat)
with specified resolution.
Syntax
geoToH3(lon, lat, resolution)
Arguments
lon
β Longitude. Type: Float64.lat
β Latitude. Type: Float64.resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned values
- Hexagon index number.
- 0 in case of error.
Type: UInt64.
Example
Query:
SELECT geoToH3(37.79506683, 55.71290588, 15) AS h3Index;
Result:
βββββββββββββh3Indexββ
β 644325524701193974 β
ββββββββββββββββββββββ
h3ToGeoβ
Returns the centroid longitude and latitude corresponding to the provided H3 index.
Syntax
h3ToGeo(h3Index)
Arguments
h3Index
β H3 Index. UInt64.
Returned values
- A tuple consisting of two values:
tuple(lon,lat)
.lon
β Longitude. Float64.lat
β Latitude. Float64.
Example
Query:
SELECT h3ToGeo(644325524701193974) AS coordinates;
Result:
ββcoordinatesββββββββββββββββββββββββββββ
β (37.79506616830252,55.71290243145668) β
βββββββββββββββββββββββββββββββββββββββββ
h3ToGeoBoundaryβ
Returns array of pairs (lon, lat)
, which corresponds to the boundary of the provided H3 index.
Syntax
h3ToGeoBoundary(h3Index)
Arguments
h3Index
β H3 Index. Type: UInt64.
Returned values
Example
Query:
SELECT h3ToGeoBoundary(644325524701193974) AS coordinates;
Result:
ββh3ToGeoBoundary(599686042433355775)βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [(37.2713558667319,-121.91508032705622),(37.353926450852256,-121.8622232890249),(37.42834118609435,-121.92354999630156),(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044),(37.26319797461824,-122.02910130919001)] β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
h3kRingβ
Lists all the H3 hexagons in the raduis of k
from the given hexagon in random order.
Syntax
h3kRing(h3index, k)
Arguments
Returned values
- Array of H3 indexes.
Example
Query:
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;
Result:
βββββββββββββh3indexββ
β 644325529233966508 β
β 644325529233966497 β
β 644325529233966510 β
β 644325529233966504 β
β 644325529233966509 β
β 644325529233966355 β
β 644325529233966354 β
ββββββββββββββββββββββ
h3GetBaseCellβ
Returns the base cell number of the H3 index.
Syntax
h3GetBaseCell(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Hexagon base cell number.
Type: UInt8.
Example
Query:
SELECT h3GetBaseCell(612916788725809151) AS basecell;
Result:
ββbasecellββ
β 12 β
ββββββββββββ
h3HexAreaM2β
Returns average hexagon area in square meters at the given resolution.
Syntax
h3HexAreaM2(resolution)
Parameter
resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned value
- Area in square meters.
Type: Float64.
Example
Query:
SELECT h3HexAreaM2(13) AS area;
Result:
ββareaββ
β 43.9 β
ββββββββ
h3HexAreaKm2β
Returns average hexagon area in square kilometers at the given resolution.
Syntax
h3HexAreaKm2(resolution)
Parameter
resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned value
- Area in square kilometers.
Type: Float64.
Example
Query:
SELECT h3HexAreaKm2(13) AS area;
Result:
βββββββareaββ
β 0.0000439 β
βββββββββββββ
h3IndexesAreNeighborsβ
Returns whether or not the provided H3 indexes are neighbors.
Syntax
h3IndexesAreNeighbors(index1, index2)
Arguments
Returned value
1
β Indexes are neighbours.0
β Indexes are not neighbours.
Type: UInt8.
Example
Query:
SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;
Result:
ββnββ
β 1 β
βββββ
h3ToChildrenβ
Returns an array of child indexes for the given H3 index.
Syntax
h3ToChildren(index, resolution)
Arguments
index
β Hexagon index number. Type: UInt64.resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned values
- Array of the child H3-indexes.
Example
Query:
SELECT h3ToChildren(599405990164561919, 6) AS children;
Result:
ββchildrenββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
h3ToParentβ
Returns the parent (coarser) index containing the given H3 index.
Syntax
h3ToParent(index, resolution)
Arguments
index
β Hexagon index number. Type: UInt64.resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned value
- Parent H3 index.
Type: UInt64.
Example
Query:
SELECT h3ToParent(599405990164561919, 3) AS parent;
Result:
ββββββββββββββparentββ
β 590398848891879423 β
ββββββββββββββββββββββ
h3ToStringβ
Converts the H3Index
representation of the index to the string representation.
h3ToString(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- String representation of the H3 index.
Type: String.
Example
Query:
SELECT h3ToString(617420388352917503) AS h3_string;
Result:
ββh3_stringββββββββ
β 89184926cdbffff β
βββββββββββββββββββ
stringToH3β
Converts the string representation to the H3Index
(UInt64) representation.
Syntax
stringToH3(index_str)
Parameter
index_str
β String representation of the H3 index. Type: String.
Returned value
- Hexagon index number. Returns 0 on error. Type: UInt64.
Example
Query:
SELECT stringToH3('89184926cc3ffff') AS index;
Result:
βββββββββββββββindexββ
β 617420388351344639 β
ββββββββββββββββββββββ
h3GetResolutionβ
Returns the resolution of the H3 index.
Syntax
h3GetResolution(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Index resolution. Range:
[0, 15]
. Type: UInt8.
Example
Query:
SELECT h3GetResolution(617420388352917503) AS res;
Result:
ββresββ
β 9 β
βββββββ
h3IsResClassIIIβ
Returns whether H3 index has a resolution with Class III orientation.
Syntax
h3IsResClassIII(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
1
β Index has a resolution with Class III orientation.0
β Index doesn't have a resolution with Class III orientation.
Type: UInt8.
Example
Query:
SELECT h3IsResClassIII(617420388352917503) AS res;
Result:
ββresββ
β 1 β
βββββββ
h3IsPentagonβ
Returns whether this H3 index represents a pentagonal cell.
Syntax
h3IsPentagon(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
1
β Index represents a pentagonal cell.0
β Index doesn't represent a pentagonal cell.
Type: UInt8.
Example
Query:
SELECT h3IsPentagon(644721767722457330) AS pentagon;
Result:
ββpentagonββ
β 0 β
ββββββββββββ
h3GetFacesβ
Returns icosahedron faces intersected by a given H3 index.
Syntax
h3GetFaces(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned values
- Array containing icosahedron faces intersected by a given H3 index.
Example
Query:
SELECT h3GetFaces(599686042433355775) AS faces;
Result:
ββfacesββ
β [7] β
βββββββββ
h3CellAreaM2β
Returns the exact area of a specific cell in square meters corresponding to the given input H3 index.
Syntax
h3CellAreaM2(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Cell area in square meters.
Type: Float64.
Example
Query:
SELECT h3CellAreaM2(579205133326352383) AS area;
Result:
ββββββββββββββββareaββ
β 4106166334463.9233 β
ββββββββββββββββββββββ
h3CellAreaRads2β
Returns the exact area of a specific cell in square radians corresponding to the given input H3 index.
Syntax
h3CellAreaRads2(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Cell area in square radians.
Type: Float64.
Example
Query:
SELECT h3CellAreaRads2(579205133326352383) AS area;
Result:
βββββββββββββββββareaββ
β 0.10116268528089567 β
βββββββββββββββββββββββ
h3ToCenterChildβ
Returns the center child (finer) H3 index contained by given H3 at the given resolution.
Syntax
h3ToCenterChild(index, resolution)
Parameter
index
β Hexagon index number. Type: UInt64.resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned values
Type: UInt64.
Example
Query:
SELECT h3ToCenterChild(577023702256844799,1) AS centerToChild;
Result:
βββββββcenterToChildββ
β 581496515558637567 β
ββββββββββββββββββββββ
h3ExactEdgeLengthMβ
Returns the exact edge length of the unidirectional edge represented by the input h3 index in meters.
Syntax
h3ExactEdgeLengthM(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Exact edge length in meters.
Type: Float64.
Example
Query:
SELECT h3ExactEdgeLengthM(1310277011704381439) AS exactEdgeLengthM;;
Result:
ββββexactEdgeLengthMββ
β 195449.63163407316 β
ββββββββββββββββββββββ
h3ExactEdgeLengthKmβ
Returns the exact edge length of the unidirectional edge represented by the input h3 index in kilometers.
Syntax
h3ExactEdgeLengthKm(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Exact edge length in kilometers.
Type: Float64.
Example
Query:
SELECT h3ExactEdgeLengthKm(1310277011704381439) AS exactEdgeLengthKm;;
Result:
βββexactEdgeLengthKmββ
β 195.44963163407317 β
ββββββββββββββββββββββ
h3ExactEdgeLengthRadsβ
Returns the exact edge length of the unidirectional edge represented by the input h3 index in radians.
Syntax
h3ExactEdgeLengthRads(index)
Parameter
index
β Hexagon index number. Type: UInt64.
Returned value
- Exact edge length in radians.
Type: Float64.
Example
Query:
SELECT h3ExactEdgeLengthRads(1310277011704381439) AS exactEdgeLengthRads;;
Result:
βββexactEdgeLengthRadsββ
β 0.030677980118976447 β
ββββββββββββββββββββββββ
h3NumHexagonsβ
Returns the number of unique H3 indices at the given resolution.
Syntax
h3NumHexagons(resolution)
Parameter
resolution
β Index resolution. Range:[0, 15]
. Type: UInt8.
Returned value
- Number of H3 indices.
Type: Int64.
Example
Query:
SELECT h3NumHexagons(3) AS numHexagons;
Result:
ββnumHexagonsββ
β 41162 β
βββββββββββββββ
h3Lineβ
Returns the line of indices between the two indices that are provided.
Syntax
h3Line(start,end)
Parameter
start
β Hexagon index number that represents a starting point. Type: UInt64.end
β Hexagon index number that represents an ending point. Type: UInt64.
Returned value
Array of h3 indexes representing the line of indices between the two provided indices:
Example
Query:
SELECT h3Line(590080540275638271,590103561300344831) as indexes;
Result:
ββindexesβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [590080540275638271,590080471556161535,590080883873021951,590106516237844479,590104385934065663,590103630019821567,590103561300344831] β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
h3Distanceβ
Returns the distance in grid cells between the two indices that are provided.
Syntax
h3Distance(start,end)
Parameter
start
β Hexagon index number that represents a starting point. Type: UInt64.end
β Hexagon index number that represents an ending point. Type: UInt64.
Returned value
- Number of grid cells.
Type: Int64.
Returns a negative number if finding the distance fails.
Example
Query:
SELECT h3Distance(590080540275638271,590103561300344831) as distance;
Result:
ββdistanceββ
β 7 β
ββββββββββββ
h3HexRingβ
Returns the indexes of the hexagonal ring centered at the provided origin h3Index and length k.
Returns 0 if no pentagonal distortion was encountered.
Syntax
h3HexRing(index, k)
Parameter
index
β Hexagon index number that represents the origin. Type: UInt64.k
β Distance. Type: UInt64.
Returned values
- Array of H3 indexes.
Example
Query:
SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;
Result:
ββhexRingββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ