H3_HEX_RING

Return the array of H3 cells on the ring exactly k grid steps from a center cell.

Category: h3Returns: ARRAY<BIGINT>Dialect: Standard

Syntax

H3_HEX_RING(cell, k)

Description

## Overview Returns an array of H3 cells that are exactly k grid steps from the input center cell, forming a hollow hex ring. Unlike H3_HEX_DISK, which returns the full filled disk, H3_HEX_RING returns only the outermost boundary at distance k. For a hexagon center, this ring contains exactly 6k cells (5k when the center is a pentagon, or fewer when the ring itself crosses a pentagon). Use it for donut-shaped proximity checks (cells at a specific distance but not closer), for fingerprinting a neighborhood boundary, for counting cells in a distance band, and for efficient set-subtraction of concentric disks. ## Behavior - Returns an ARRAY<BIGINT> of exactly 6k cells for a hexagon center (fewer when pentagons are involved). - k=0 returns a single-element array containing the center cell. - k=1 returns the 6 (or 5) immediate neighbors. - Returns NULL if the center cell is NULL or invalid. - Returns NULL if k is negative or produces a ring larger than the internal limit. - Near pentagons, the ring may be smaller than 6k or may return NULL when the pentagon distortion makes the ring ill-defined. - The order of elements is deterministic but not sorted and is not a strict walk around the ring. ## H3 resolution reference | Res | Edge length | k=1 radius | k=10 radius | | --- | --- | --- | --- | | 7 | 1.22 km | ~1.2 km | ~12 km | | 9 | 174 m | ~174 m | ~1.74 km | | 10 | 65.9 m | ~66 m | ~660 m | | 12 | 9.4 m | ~9.4 m | ~94 m | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for hex ring expansion.

Parameters

Name	Type	Description
`cell`		Specifies the center H3 cell. Must be a valid H3 cell.
`k`		Specifies the ring radius as a non-negative integer number of hex steps. k=0 returns only the center, k=1 returns the six immediate neighbors (five for a pentagon center).

Examples

-- k=1: 6 cells for a hexagon center, 5 for a pentagon center.
SELECT H3_HEX_RING(H3_LATLNG_TO_CELL(51.5074, -0.1278, 9), 1) AS ring_k1;

-- A hollow ring contains exactly 6k cells for a hexagon center: 18 cells at k=3.
SELECT SIZE(H3_HEX_RING(H3_LATLNG_TO_CELL(40.7128, -74.0060, 9), 3)) AS ring_size;

-- Use a ring (not a disk) to pick only the cells at a specific distance band.
SELECT e.event_id
FROM analytics.curated.h3_events_res9 e
WHERE e.h3_cell IN (SELECT EXPLODE(H3_HEX_RING(H3_LATLNG_TO_CELL(48.8566, 2.3522, 9), 5)));

-- Disk at k = union of all rings 0..k; ring is only distance-k cells.
SELECT
  SIZE(H3_HEX_DISK(c, 2)) AS disk_k2,
  SIZE(H3_HEX_RING(c, 2)) AS ring_k2
FROM (SELECT H3_LATLNG_TO_CELL(35.6762, 139.6503, 9) AS c);

-- A ring adjacent to a pentagon may return NULL because the pentagon deformation prevents a clean ring definition.
SELECT H3_HEX_RING(pentagon_neighbor_cell, 2)
FROM diagnostics.h3_pentagon_neighbors
LIMIT 1;

Pitfalls

H3_HEX_RING returns only the cells at exactly k steps; H3_HEX_DISK returns every cell within k steps. Using one where you meant the other changes the result size by a factor of k.
Rings near a pentagon may be shorter than 6k or may return NULL entirely. Handle NULL in code that scans large regions at fine resolutions.
The count of cells grows linearly in k (6k for hexagons); a ring at k=100 is 600 cells. This is much smaller than the corresponding disk (~30,000) but still worth bounding.
Rings are hex-step rings, not metric rings. The physical radius varies with resolution; use H3_EDGE_LENGTH to convert to meters approximately.
When the center is itself a pentagon, the k=1 ring has 5 cells not 6, and deeper rings have further deficits proportional to the pentagon count encountered.