geo_h3cell_rings()

Learn how to use the geo_h3cell_rings() function to calculate the H3 cell rings.

Calculates the H3 cell Rings.

Read more about H3 Cell.

Syntax

geo_h3cell_rings(h3cell,distance)

Parameters

NameTypeRequiredDescription
h3cellstring✔️An H3 Cell token value as it was calculated by geo_point_to_h3cell().
distanceint✔️Defines the maximum ring distance from given cell. Valid distance is in range [0, 142].

Returns

An ordered array of ring arrays where first ring contains the original cell, second ring contains neighboring cells, and so on. If either the H3 Cell or distance is invalid, the query produces a null result.

Examples

The following example produces rings up to distance 2.

print rings = geo_h3cell_rings('861f8894fffffff', 2)

Output

rings
[
[“861f8894fffffff”],
[“861f88947ffffff”,“861f8895fffffff”,“861f88867ffffff”,“861f8d497ffffff”,“861f8d4b7ffffff”,“861f8896fffffff”],
[“861f88967ffffff”,“861f88977ffffff”,“861f88957ffffff”,“861f8882fffffff”,“861f88877ffffff”,“861f88847ffffff”,“861f8886fffffff”,“861f8d49fffffff”,“861f8d487ffffff”,“861f8d4a7ffffff”,“861f8d59fffffff”,“861f8d597ffffff”]
]

The following example produces all cells at level 1 (all neighbors).

print neighbors = geo_h3cell_rings('861f8894fffffff', 1)[1]

Output

neighbors
[“861f88947ffffff”, “861f8895fffffff”, “861f88867ffffff”, “861f8d497ffffff”, “861f8d4b7ffffff”,“861f8896fffffff”]

The following example produces list of cells from all rings.

print rings = geo_h3cell_rings('861f8894fffffff', 1)
| mv-apply rings on 
(
  summarize cells = make_list(rings)
)

Output

cells
[“861f8894fffffff”,“861f88947ffffff”,“861f8895fffffff”,“861f88867ffffff”,“861f8d497ffffff”,“861f8d4b7ffffff”,“861f8896fffffff”]

The following example assembles GeoJSON geometry collection of all cells.

print rings = geo_h3cell_rings('861f8894fffffff', 1)
| mv-apply rings on 
(
  summarize make_list(rings)
)
| mv-expand list_rings to typeof(string)
| project polygon = geo_h3cell_to_polygon(list_rings)
| summarize polygon_lst = make_list(polygon)
| project geojson = bag_pack(
    "type", "Feature",
    "geometry", bag_pack("type", "GeometryCollection", "geometries", polygon_lst),
    "properties", bag_pack("name", "H3 polygons collection"))

Output

geojson
{ “type”: “Feature”, “geometry”: { “type”: “GeometryCollection”, “geometries”: [ … … … ]}, “properties”: { “name”: “H3 polygons collection” }}

The following example returns true because of the invalid cell.

print is_null = isnull(geo_h3cell_rings('abc', 3))

Output

is_null
1

The following example returns true because of the invalid distance.

print is_null = isnull(geo_h3cell_rings('861f8894fffffff', 150))

Output

is_null
1