34 KiB
slug | sidebar_label | title |
---|---|---|
/en/sql-reference/functions/geo/h3 | H3 Indexes | Functions for Working with H3 Indexes |
H3 Index
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 split 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 Engineering site.
h3IsValid
Verifies whether the number is a valid H3 index.
Syntax
h3IsValid(h3index)
Parameter
h3index
— Hexagon index number. UInt64.
Returned values
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. UInt64.
Returned values
- Index resolution. Range:
[0, 15]
. UInt8. - If the index is not valid, the function returns a random value. Use h3IsValid to verify the index. 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. 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. 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. 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. Float64.lat
— Latitude. Float64.resolution
— Index resolution. Range:[0, 15]
. UInt8.
Returned values
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. 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
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. UInt64.
Returned value
- Hexagon base cell number. 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]
. UInt8.
Returned value
- Area in square meters. 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]
. UInt8.
Returned value
- Area in square kilometers. 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
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
Returned values
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
Returned value
- Parent H3 index. 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. UInt64.
Returned value
- String representation of the H3 index. 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. String.
Returned value
- Hexagon index number. Returns 0 on error. 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. UInt64.
Returned value
- Index resolution. Range:
[0, 15]
. 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. UInt64.
Returned value
1
— Index has a resolution with Class III orientation. UInt8.0
— Index doesn't have a resolution with Class III orientation. 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. UInt64.
Returned value
1
— Index represents a pentagonal cell. UInt8.0
— Index doesn't represent a pentagonal cell. 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. UInt64.
Returned values
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. UInt64.
Returned value
- Cell area in square meters. 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. UInt64.
Returned value
- Cell area in square radians. 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
Returned values
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. UInt64.
Returned value
- Exact edge length in meters. 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. UInt64.
Returned value
- Exact edge length in kilometers. 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. UInt64.
Returned value
- Exact edge length in radians. 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]
. UInt8.
Returned value
- Number of H3 indices. Int64.
Example
Query:
SELECT h3NumHexagons(3) AS numHexagons;
Result:
┌─numHexagons─┐
│ 41162 │
└─────────────┘
h3PointDistM
Returns the "great circle" or "haversine" distance between pairs of GeoCoord points (latitude/longitude) pairs in meters.
Syntax
h3PointDistM(lat1, lon1, lat2, lon2)
Arguments
lat1
,lon1
— Latitude and Longitude of point1 in degrees. Float64.lat2
,lon2
— Latitude and Longitude of point2 in degrees. Float64.
Returned values
- Haversine or great circle distance in meters.Float64.
Example
Query:
select h3PointDistM(-10.0 ,0.0, 10.0, 0.0) as h3PointDistM;
Result:
┌──────h3PointDistM─┐
│ 2223901.039504589 │
└───────────────────┘
h3PointDistKm
Returns the "great circle" or "haversine" distance between pairs of GeoCoord points (latitude/longitude) pairs in kilometers.
Syntax
h3PointDistKm(lat1, lon1, lat2, lon2)
Arguments
lat1
,lon1
— Latitude and Longitude of point1 in degrees. Float64.lat2
,lon2
— Latitude and Longitude of point2 in degrees. Float64.
Returned values
- Haversine or great circle distance in kilometers. Float64.
Example
Query:
select h3PointDistKm(-10.0 ,0.0, 10.0, 0.0) as h3PointDistKm;
Result:
┌─────h3PointDistKm─┐
│ 2223.901039504589 │
└───────────────────┘
h3PointDistRads
Returns the "great circle" or "haversine" distance between pairs of GeoCoord points (latitude/longitude) pairs in radians.
Syntax
h3PointDistRads(lat1, lon1, lat2, lon2)
Arguments
lat1
,lon1
— Latitude and Longitude of point1 in degrees. Float64.lat2
,lon2
— Latitude and Longitude of point2 in degrees. Float64.
Returned values
- Haversine or great circle distance in radians. Float64.
Example
Query:
select h3PointDistRads(-10.0 ,0.0, 10.0, 0.0) as h3PointDistRads;
Result:
┌────h3PointDistRads─┐
│ 0.3490658503988659 │
└────────────────────┘
h3GetRes0Indexes
Returns an array of all the resolution 0 H3 indexes.
Syntax
h3GetRes0Indexes()
Returned values
Example
Query:
select h3GetRes0Indexes as indexes ;
Result:
┌─indexes─────────────────────────────────────┐
│ [576495936675512319,576531121047601151,....]│
└─────────────────────────────────────────────┘
h3GetPentagonIndexes
Returns all the pentagon H3 indexes at the specified resolution.
Syntax
h3GetPentagonIndexes(resolution)
Parameter
resolution
— Index resolution. Range:[0, 15]
. UInt8.
Returned value
Example
Query:
SELECT h3GetPentagonIndexes(3) AS indexes;
Result:
┌─indexes────────────────────────────────────────────────────────┐
│ [590112357393367039,590464201114255359,590816044835143679,...] │
└────────────────────────────────────────────────────────────────┘
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. UInt64.end
— Hexagon index number that represents an ending point. UInt64.
Returned value
Array of h3 indexes representing the line of indices between the two provided indices. Array(UInt64).
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. UInt64.end
— Hexagon index number that represents an ending point. UInt64.
Returned value
- Number of grid cells. 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
Returned values
Example
Query:
SELECT h3HexRing(590080540275638271, toUInt16(1)) AS hexRing;
Result:
┌─hexRing─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [590080815153545215,590080471556161535,590080677714591743,590077585338138623,590077447899185151,590079509483487231] │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3GetUnidirectionalEdge
Returns a unidirectional edge H3 index based on the provided origin and destination and returns 0 on error.
Syntax
h3GetUnidirectionalEdge(originIndex, destinationIndex)
Parameter
originIndex
— Origin Hexagon index number. UInt64.destinationIndex
— Destination Hexagon index number. UInt64.
Returned value
- Unidirectional Edge Hexagon Index number. UInt64.
Example
Query:
SELECT h3GetUnidirectionalEdge(599686042433355775, 599686043507097599) as edge;
Result:
┌────────────────edge─┐
│ 1248204388774707199 │
└─────────────────────┘
h3UnidirectionalEdgeIsValid
Determines if the provided H3Index is a valid unidirectional edge index. Returns 1 if it's a unidirectional edge and 0 otherwise.
Syntax
h3UnidirectionalEdgeisValid(index)
Parameter
index
— Hexagon index number. UInt64.
Returned value
- 1 — The H3 index is a valid unidirectional edge. UInt8.
- 0 — The H3 index is not a valid unidirectional edge. UInt8.
Example
Query:
SELECT h3UnidirectionalEdgeIsValid(1248204388774707199) as validOrNot;
Result:
┌─validOrNot─┐
│ 1 │
└────────────┘
h3GetOriginIndexFromUnidirectionalEdge
Returns the origin hexagon index from the unidirectional edge H3Index.
Syntax
h3GetOriginIndexFromUnidirectionalEdge(edge)
Parameter
edge
— Hexagon index number that represents a unidirectional edge. UInt64.
Returned value
- Origin Hexagon Index number. UInt64.
Example
Query:
SELECT h3GetOriginIndexFromUnidirectionalEdge(1248204388774707197) as origin;
Result:
┌─────────────origin─┐
│ 599686042433355773 │
└────────────────────┘
h3GetDestinationIndexFromUnidirectionalEdge
Returns the destination hexagon index from the unidirectional edge H3Index.
Syntax
h3GetDestinationIndexFromUnidirectionalEdge(edge)
Parameter
edge
— Hexagon index number that represents a unidirectional edge. UInt64.
Returned value
- Destination Hexagon Index number. UInt64.
Example
Query:
SELECT h3GetDestinationIndexFromUnidirectionalEdge(1248204388774707197) as destination;
Result:
┌────────destination─┐
│ 599686043507097597 │
└────────────────────┘
h3GetIndexesFromUnidirectionalEdge
Returns the origin and destination hexagon indexes from the given unidirectional edge H3Index.
Syntax
h3GetIndexesFromUnidirectionalEdge(edge)
Parameter
edge
— Hexagon index number that represents a unidirectional edge. UInt64.
Returned value
A tuple consisting of two values tuple(origin,destination)
:
origin
— Origin Hexagon index number. UInt64.destination
— Destination Hexagon index number. UInt64.
Returns (0,0)
if the provided input is not valid.
Example
Query:
SELECT h3GetIndexesFromUnidirectionalEdge(1248204388774707199) as indexes;
Result:
┌─indexes─────────────────────────────────┐
│ (599686042433355775,599686043507097599) │
└─────────────────────────────────────────┘
h3GetUnidirectionalEdgesFromHexagon
Provides all of the unidirectional edges from the provided H3Index.
Syntax
h3GetUnidirectionalEdgesFromHexagon(index)
Parameter
index
— Hexagon index number that represents a unidirectional edge. UInt64.
Returned value
Array of h3 indexes representing each unidirectional edge. Array(UInt64).
Example
Query:
SELECT h3GetUnidirectionalEdgesFromHexagon(1248204388774707199) as edges;
Result:
┌─edges─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [1248204388774707199,1320261982812635135,1392319576850563071,1464377170888491007,1536434764926418943,1608492358964346879] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
h3GetUnidirectionalEdgeBoundary
Returns the coordinates defining the unidirectional edge.
Syntax
h3GetUnidirectionalEdgeBoundary(index)
Parameter
index
— Hexagon index number that represents a unidirectional edge. UInt64.
Returned value
Example
Query:
SELECT h3GetUnidirectionalEdgeBoundary(1248204388774707199) as boundary;
Result:
┌─boundary────────────────────────────────────────────────────────────────────────┐
│ [(37.42012867767779,-122.03773496427027),(37.33755608435299,-122.090428929044)] │
└─────────────────────────────────────────────────────────────────────────────────┘