mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-11 08:52:06 +00:00

bharatnc 3342c64110 Merge remote-tracking branch 'upstream/master' into ncb/h3-misc-funcs

2022-01-20 20:21:56 -08:00

22 KiB

Raw Blame History

toc_title
H3 Indexes

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

The average length of the H3 hexagon edge in grades. Type: Float64.

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

The average length of the H3 hexagon edge in meters. Type: Float64.

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

The average length of the H3 hexagon edge in kilometers. Type: Float64.

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

Array of pairs '(lon, lat)'. Type: Array(Float64, Float64).

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

h3index — Hexagon index number. Type: UInt64.
k — Radius. Type: integer

Returned values

Array of H3 indexes.

Type: Array(UInt64).

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

index1 — Hexagon index number. Type: UInt64.
index2 — Hexagon index number. Type: UInt64.

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.

Type: Array(UInt64).

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.

Type: Array(UInt64).

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

H3 index of the center child contained by given H3 at the given resolution.

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 │
└─────────────┘

Original article

22 KiB Raw Blame History Unescape Escape

Functions for Working with H3 Indexes

h3IsValid

h3GetResolution

h3EdgeAngle

h3EdgeLengthM

h3EdgeLengthKm

geoToH3

h3ToGeo

h3ToGeoBoundary

h3kRing

h3GetBaseCell

h3HexAreaM2

h3HexAreaKm2

h3IndexesAreNeighbors

h3ToChildren

h3ToParent

h3ToString

stringToH3

h3GetResolution

h3IsResClassIII

h3IsPentagon

h3GetFaces

h3CellAreaM2

h3CellAreaRads2

h3ToCenterChild

h3ExactEdgeLengthM

h3ExactEdgeLengthKm

h3ExactEdgeLengthRads

h3NumHexagons

22 KiB

Raw Blame History