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