geo_h3cell_rings()

Applies to: ✅ Microsoft FabricAzure Data ExplorerAzure MonitorMicrosoft 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