geo_h3cell_rings()

Applies to: ✅ Microsoft Fabric ✅ Azure Data Explorer ✅ Azure Monitor ✅ Microsoft Sentinel

Calculates the H3 cell Rings.

Read more about H3 Cell.

Syntax

geo_h3cell_rings(h3cell,distance)

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
h3cell	string	✔️	An H3 Cell token value as it was calculated by geo_point_to_h3cell().
distance	int	✔️	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.

Note

• For H3 Cell immediate neighbors only, please see geo_h3cell_neighbors().
• A cell might be not present in the ring if pentagonal distortion was encountered.

Examples

The following example produces rings up to distance 2.

Run the query

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).

Run the query

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.

Run the query

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.

Run the query

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.

Run the query

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

Output

is_null
1

The following example returns true because of the invalid distance.

Run the query

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

Output

is_null
1