title_wip

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/sql-reference/functions/geo/h3.md)

## H3 Index[​](#h3-index "Direct link to H3 Index")

[H3](https://h3geo.org/) is a geographical indexing system where the Earth's surface is 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](https://www.uber.com/blog/h3/).

## h3IsValid[​](#h3isvalid "Direct link to h3IsValid")

Verifies whether the number is a valid [H3](#h3-index) index.

**Syntax**

```
h3IsValid(h3index)
```

**Parameter**

- `h3index` — Hexagon index number. [UInt64](/docs/sql-reference/data-types/int-uint).

**Returned values**

- 1 — The number is a valid H3 index. [UInt8](/docs/sql-reference/data-types/int-uint).
- 0 — The number is not a valid H3 index. [UInt8](/docs/sql-reference/data-types/int-uint).

**Example**

Query:

```
SELECT h3IsValid(630814730351855103) AS h3IsValid;
```

Result:

```
┌─h3IsValid─┐
│         1 │
└───────────┘
```

## h3GetResolution[​](#h3getresolution "Direct link to h3GetResolution")

Defines the resolution of the given [H3](#h3-index) index.

**Syntax**

```
h3GetResolution(h3index)
```

**Parameter**

- `h3index` — Hexagon index number. [UInt64](/docs/sql-reference/data-types/int-uint).

**Returned values**

- Index resolution. Range: `[0, 15]`. [UInt8](/docs/sql-reference/data-types/int-uint).
- If the index is not valid, the function returns a random value. Use [h3IsValid](#h3isvalid) to verify the index. [UInt8](/docs/sql-reference/data-types/int-uint).

**Example**

Query:

```
SELECT h3GetResolution(639821929606596015) AS resolution;
```

Result:

```
┌─resolution─┐
│         14 │
└────────────┘
```

## h3EdgeAngle[​](#h3edgeangle "Direct link to h3EdgeAngle")

Calculates the average length of an [H3](#h3-index) hexagon edge in grades.

**Syntax**

```
h3EdgeAngle(resolution)
```

**Parameter**

- `resolution` — Index resolution. [UInt8](/docs/sql-reference/data-types/int-uint). Range: `[0, 15]`.

**Returned values**

- The average length of an [H3](#h3-index) hexagon edge in grades. [Float64](/docs/sql-reference/data-types/float).

**Example**

Query:

```
SELECT h3EdgeAngle(10) AS edgeAngle;
```

Result:

```
┌───────h3EdgeAngle(10)─┐
│ 0.0005927224846720883 │
└───────────────────────┘
```

## h3EdgeLengthM[​](#h3edgelengthm "Direct link to h3EdgeLengthM")

Calculates the average length of an [H3](#h3-index) hexagon edge in meters.

**Syntax**

```
h3EdgeLengthM(resolution)
```

**Parameter**

- `resolution` — Index resolution. [UInt8](/docs/sql-reference/data-types/int-uint). Range: `[0, 15]`.

**Returned values**

- The average edge length of an [H3](#h3-index) hexagon in meters. [Float64](/docs/sql-reference/data-types/float).

**Example**

Query:

```
SELECT h3EdgeLengthM(15) AS edgeLengthM;
```

Result:

```
┌─edgeLengthM─┐
│ 0.509713273 │
└─────────────┘
```

## h3EdgeLengthKm[​](#h3edgelengthkm "Direct link to h3EdgeLengthKm")

Calculates the average length of an [H3](#h3-index) hexagon edge in kilometers.

**Syntax**

```
h3EdgeLengthKm(resolution)
```

**Parameter**

- `resolution` — Index resolution. [UInt8](/docs/sql-reference/data-types/int-uint). Range: `[0, 15]`.

**Returned values**

- The average length of an [H3](#h3-index) hexagon edge in kilometers. [Float64](/docs/sql-reference/data-types/float).

**Example**

Query:

```
SELECT h3EdgeLengthKm(15) AS edgeLengthKm;
```

Result:

```
┌─edgeLengthKm─┐
│  0.000509713 │
└──────────────┘
```

## geoToH3[​](#geotoh3 "Direct link to geoToH3")

Returns [H3](#h3-index) point index `(lat, lon)` with specified resolution.

**Syntax**

```
geoToH3(lat, lon, resolution)
```

**Arguments**

- `lat` — Latitude. [Float64](/docs/sql-reference/data-types/float).
- `lon` — Longitude. [Float64](/docs/sql-reference/data-types/float).
- `resolution` — Index resolution. Range: `[0, 15]`. [UInt8](/docs/sql-reference/data-types/int-uint).

**Returned values**

- Hexagon index number. [UInt64](/docs/sql-reference/data-types/int-uint).
- 0 in case of error. [UInt64](/docs/sql-reference/data-types/int-uint).

Note: In ClickHouse v25.4 or older, `geoToH3()` takes values in order `(lon, lat)`. As per ClickHouse v25.5, the input values are in order `(lat, lon)`. The previous behaviour can be restored using setting `geotoh3_argument_order = 'lon_lat'`.

**Example**

Query:

```
SELECT geoToH3(55.71290588, 37.79506683, 15) AS h3Index;
```

Result:

```
┌────────────h3Index─┐
│ 644325524701193974 │
└────────────────────┘
```

## h3ToGeo[​](#h3togeo "Direct link to h3ToGeo")

Returns the centroid latitude and longitude corresponding to the provided [H3](#h3-index) index.

**Syntax**

```
h3ToGeo(h3Index)
```

**Arguments**

- `h3Index` — H3 Index. [UInt64](/docs/sql-reference/data-types/int-uint).

**Returned values**

- A tuple consisting of two values: `tuple(lat,lon)`. `lat` — Latitude. [Float64](/docs/sql-reference/data-types/float). `lon` — Longitude. [Float64](/docs/sql-reference/data-types/float).

Note: In ClickHouse v24.12 or older, `h3ToGeo()` returns values in order `(lon, lat)`. As per ClickHouse v25.1, the returned values are in order `(lat, lon)`. The previous behaviour can be restored using setting `h3togeo_lon_lat_result_order = true`.

**Example**

Query:

```
SELECT h3ToGeo(644325524701193974) AS coordinates;
```

Result:

```
┌─coordinates───────────────────────────┐
│ (55.71290243145668,37.79506616830252) │
└───────────────────────────────────────┘
```

## h3ToGeoBoundary[​](#h3togeoboundary "Direct link to h3ToGeoBoundary")

Returns array of pairs `(lat, lon)`, which corresponds to the boundary of the provided H3 index.

**Syntax**

```
h3ToGeoBoundary(h3Index)
```

**Arguments**

- `h3Index` — H3 Index. [UInt64](/docs/sql-reference/data-types/int-uint).

**Returned values**

- Array of pairs '(lat, lon)'. [Array](/docs/sql-reference/data-types/array)([Float64](/docs/sql-reference/data-types/float), [Float64](/docs/sql-reference/data-types/float)).

**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[​](#h3kring "Direct link to h3kRing")

Lists all the [H3](#h3-index) hexagons in the raduis of `k` from the given hexagon in random order.

**Syntax**

```
h3kRing(h3index, k)
```

**Arguments**

- `h3index` — Hexagon index number. [UInt64](/docs/sql-reference/data-types/int-uint).
- `k` — Radius. [integer](/docs/sql-reference/data-types/int-uint)

**Returned values**

- Array of H3 indexes. [Array](/docs/sql-reference/data-types/array)([UInt64](/docs/sql-reference/data-types/int-uint)).

**Example**

Query:

```
SELECT arrayJoin(h3kRing(644325529233966508, 1)) AS h3index;
```

Result:

```
┌────────────h3index─┐
│ 644325529233966508 │
│ 644325529233966497 │
│ 644325529233966510 │
│ 644325529233966504 │
│ 644325529233966509 │
│ 644325529233966355 │
│ 644325529233966354 │
└────────────────────┘
```