ClickHouse/docs/en/sql-reference/functions/geo/h3.md
olgarev e2287959a8
DOCSUP-1585: Edit and sync geo functions (#12584)
* Geo functions - en/ru sync.

* Fixed bug with levels.

* Apply suggestions from code review

Co-authored-by: Ivan Blinkov <github@blinkov.ru>
Co-authored-by: BayoNet <da-daos@yandex.ru>

* Geo functions splitted into 3 files.

* Links fixed.

* Link fixed.

* Anchor fixed.

* Add into TOC.

* Temporarily removed anchors.

* Working on TOC.

* Links to original article.

* TOC and links in English and Russian.

* TOC in English, content in index.

* Link fixed.

* TOC in Russian, with content in index file.

* Added index file to geo functions

* fixed links in ru

Co-authored-by: Olga Revyakina <revolg@yandex-team.ru>
Co-authored-by: Ivan Blinkov <github@blinkov.ru>
Co-authored-by: BayoNet <da-daos@yandex.ru>
Co-authored-by: Sergei Shtykov <bayonet@yandex-team.ru>
2020-07-28 10:57:28 +03:00

523 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
toc_title: H3 Indexes
---
# Functions for Working with H3 Indexes {#h3index}
[H3](https://eng.uber.com/h3/) is a geographical indexing system where Earths 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](https://eng.uber.com/h3/).
## h3IsValid {#h3isvalid}
Verifies whether the number is a valid [H3](#h3index) index.
**Syntax**
``` sql
h3IsValid(h3index)
```
**Parameter**
- `h3index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned values**
- 1 — The number is a valid H3 index.
- 0 — The number is not a valid H3 index.
Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3IsValid(630814730351855103) as h3IsValid
```
Result:
``` text
┌─h3IsValid─┐
│ 1 │
└───────────┘
```
## h3GetResolution {#h3getresolution}
Defines the resolution of the given [H3](#h3index) index.
**Syntax**
``` sql
h3GetResolution(h3index)
```
**Parameter**
- `h3index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned values**
- Index resolution. Range: `[0, 15]`.
- If the index is not valid, the function returns a random value. Use [h3IsValid](#h3isvalid) to verify the index.
Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3GetResolution(639821929606596015) as resolution
```
Result:
``` text
┌─resolution─┐
│ 14 │
└────────────┘
```
## h3EdgeAngle {#h3edgeangle}
Calculates the average length of the [H3](#h3index) hexagon edge in grades.
**Syntax**
``` sql
h3EdgeAngle(resolution)
```
**Parameter**
- `resolution` — Index resolution. Type: [UInt8](../../../sql-reference/data-types/int-uint.md). Range: `[0, 15]`.
**Returned values**
- The average length of the [H3](#h3index) hexagon edge in grades. Type: [Float64](../../../sql-reference/data-types/float.md).
**Example**
Query:
``` sql
SELECT h3EdgeAngle(10) as edgeAngle
```
Result:
``` text
┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘
```
## h3EdgeLengthM {#h3edgelengthm}
Calculates the average length of the [H3](#h3index) hexagon edge in meters.
**Syntax**
``` sql
h3EdgeLengthM(resolution)
```
**Parameter**
- `resolution` — Index resolution. Type: [UInt8](../../../sql-reference/data-types/int-uint.md). Range: `[0, 15]`.
**Returned values**
- The average length of the [H3](#h3index) hexagon edge in meters. Type: [Float64](../../../sql-reference/data-types/float.md).
**Example**
Query:
``` sql
SELECT h3EdgeLengthM(15) as edgeLengthM
```
Result:
``` text
┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘
```
## geoToH3 {#geotoh3}
Returns [H3](#h3index) point index `(lon, lat)` with specified resolution.
**Syntax**
``` sql
geoToH3(lon, lat, resolution)
```
**Parameters**
- `lon` — Longitude. Type: [Float64](../../../sql-reference/data-types/float.md).
- `lat` — Latitude. Type: [Float64](../../../sql-reference/data-types/float.md).
- `resolution` — Index resolution. Range: `[0, 15]`. Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Returned values**
- Hexagon index number.
- 0 in case of error.
Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT geoToH3(37.79506683, 55.71290588, 15) as h3Index
```
Result:
``` text
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```
## h3kRing {#h3kring}
Lists all the [H3](#h3index) hexagons in the raduis of `k` from the given hexagon in random order.
**Syntax**
``` sql
h3kRing(h3index, k)
```
**Parameters**
- `h3index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
- `k` — Raduis. Type: [integer](../../../sql-reference/data-types/int-uint.md)
**Returned values**
- Array of H3 indexes.
Type: [Array](../../../sql-reference/data-types/array.md)([UInt64](../../../sql-reference/data-types/int-uint.md)).
**Example**
Query:
``` sql
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index
```
Result:
``` text
┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘
```
## h3GetBaseCell {#h3getbasecell}
Returns the base cell number of the [H3](#h3index) index.
**Syntax**
``` sql
h3GetBaseCell(index)
```
**Parameter**
- `index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- Hexagon base cell number.
Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3GetBaseCell(612916788725809151) as basecell;
```
Result:
``` text
┌─basecell─┐
│ 12 │
└──────────┘
```
## h3HexAreaM2 {#h3hexaream2}
Returns average hexagon area in square meters at the given resolution.
**Syntax**
``` sql
h3HexAreaM2(resolution)
```
**Parameter**
- `resolution` — Index resolution. Range: `[0, 15]`. Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- Area in square meters.
Type: [Float64](../../../sql-reference/data-types/float.md).
**Example**
Query:
``` sql
SELECT h3HexAreaM2(13) as area;
```
Result:
``` text
┌─area─┐
│ 43.9 │
└──────┘
```
## h3IndexesAreNeighbors {#h3indexesareneighbors}
Returns whether or not the provided [H3](#h3index) indexes are neighbors.
**Syntax**
``` sql
h3IndexesAreNeighbors(index1, index2)
```
**Parameters**
- `index1` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
- `index2` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- `1` — Indexes are neighbours.
- `0` — Indexes are not neighbours.
Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359) AS n;
```
Result:
``` text
┌─n─┐
│ 1 │
└───┘
```
## h3ToChildren {#h3tochildren}
Returns an array of child indexes for the given [H3](#h3index) index.
**Syntax**
``` sql
h3ToChildren(index, resolution)
```
**Parameters**
- `index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
- `resolution` — Index resolution. Range: `[0, 15]`. Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Returned values**
- Array of the child H3-indexes.
Type: [Array](../../../sql-reference/data-types/array.md)([UInt64](../../../sql-reference/data-types/int-uint.md)).
**Example**
Query:
``` sql
SELECT h3ToChildren(599405990164561919, 6) AS children;
```
Result:
``` text
┌─children───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ [603909588852408319,603909588986626047,603909589120843775,603909589255061503,603909589389279231,603909589523496959,603909589657714687] │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## h3ToParent {#h3toparent}
Returns the parent (coarser) index containing the given [H3](#h3index) index.
**Syntax**
``` sql
h3ToParent(index, resolution)
```
**Parameters**
- `index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
- `resolution` — Index resolution. Range: `[0, 15]`. Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- Parent H3 index.
Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3ToParent(599405990164561919, 3) as parent;
```
Result:
``` text
┌─────────────parent─┐
│ 590398848891879423 │
└────────────────────┘
```
## h3ToString {#h3tostring}
Converts the `H3Index` representation of the index to the string representation.
``` sql
h3ToString(index)
```
**Parameter**
- `index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- String representation of the H3 index.
Type: [String](../../../sql-reference/data-types/string.md).
**Example**
Query:
``` sql
SELECT h3ToString(617420388352917503) as h3_string;
```
Result:
``` text
┌─h3_string───────┐
│ 89184926cdbffff │
└─────────────────┘
```
## stringToH3 {#stringtoh3}
Converts the string representation to the `H3Index` (UInt64) representation.
**Syntax**
``` sql
stringToH3(index_str)
```
**Parameter**
- `index_str` — String representation of the H3 index. Type: [String](../../../sql-reference/data-types/string.md).
**Returned value**
- Hexagon index number. Returns 0 on error. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT stringToH3('89184926cc3ffff') as index;
```
Result:
``` text
┌──────────────index─┐
│ 617420388351344639 │
└────────────────────┘
```
## h3GetResolution {#h3getresolution}
Returns the resolution of the [H3](#h3index) index.
**Syntax**
``` sql
h3GetResolution(index)
```
**Parameter**
- `index` — Hexagon index number. Type: [UInt64](../../../sql-reference/data-types/int-uint.md).
**Returned value**
- Index resolution. Range: `[0, 15]`. Type: [UInt8](../../../sql-reference/data-types/int-uint.md).
**Example**
Query:
``` sql
SELECT h3GetResolution(617420388352917503) as res;
```
Result:
``` text
┌─res─┐
│ 9 │
└─────┘
```
[Original article](https://clickhouse.tech/docs/en/sql-reference/functions/geo/h3) <!--hide-->