H3_HEX_DISK

Return the array of H3 cells within k grid steps of a center cell, inclusive of the center.

Category: h3Returns: ARRAY<BIGINT>Dialect: Standard

Syntax

H3_HEX_DISK(cell, k)

Description

## Overview Returns an array of every H3 cell within k grid steps of the input center cell, inclusive of the center itself. A disk of radius 0 contains only the center, radius 1 contains the center plus its 6 immediate neighbors (5 at a pentagon center), radius 2 adds the next ring out, and so on. The total number of cells grows as 3k(k+1)+1 for a hexagon center, which is a quick way to plan query size. Use it for proximity filters, local smoothing windows, buffered spatial joins, heatmap pre-aggregation, and any pattern where you want every cell near a given anchor. ## Behavior - Returns an ARRAY<BIGINT> of all cells within k steps of the center, including the center. - Element count is 3k(k+1)+1 for a hexagon center, and one less per pentagon encountered within the disk. - Returns an array containing only the center when k=0. - Returns NULL if the input cell is NULL or invalid. - Returns NULL if k is negative or produces a disk larger than the internal limit (approximately 1,000,000 cells). - The order of elements is deterministic but not radial or sorted. - Near pentagons, some cells in the disk may be skipped internally; the result is still a valid disk of the correct size (minus pentagon deficits). ## H3 resolution reference | Res | Edge length | k=1 radius | k=5 radius | k=20 radius | | --- | --- | --- | --- | --- | | 7 | 1.22 km | ~1.2 km | ~6 km | ~24 km | | 9 | 174 m | ~174 m | ~0.87 km | ~3.5 km | | 10 | 65.9 m | ~66 m | ~330 m | ~1.3 km | | 12 | 9.4 m | ~9.4 m | ~47 m | ~188 m | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for k-disk expansion.

Parameters

Name	Type	Description
`cell`		Specifies the center H3 cell. Must be a valid H3 cell.
`k`		Specifies the disk radius in hex steps as a non-negative integer. k=0 returns only the center cell; k=1 returns the center plus the 6 (or 5 for pentagons) immediate neighbors.

Examples

-- k=1: center plus up to 6 neighbors, 7 cells total for a hexagon center.
SELECT H3_HEX_DISK(H3_LATLNG_TO_CELL(51.5074, -0.1278, 9), 1) AS disk;

-- 3k(k+1)+1 cells for a hexagon center: 1, 7, 19, 37, 61, ...
SELECT
  SIZE(H3_HEX_DISK(H3_LATLNG_TO_CELL(40.7128, -74.0060, 9), 0)) AS k0,
  SIZE(H3_HEX_DISK(H3_LATLNG_TO_CELL(40.7128, -74.0060, 9), 1)) AS k1,
  SIZE(H3_HEX_DISK(H3_LATLNG_TO_CELL(40.7128, -74.0060, 9), 2)) AS k2,
  SIZE(H3_HEX_DISK(H3_LATLNG_TO_CELL(40.7128, -74.0060, 9), 3)) AS k3;

-- Keep events in any cell within 2 steps of a reference cell.
WITH anchor AS (SELECT H3_LATLNG_TO_CELL(48.8566, 2.3522, 9) AS c)
SELECT e.event_id
FROM analytics.curated.h3_events_res9 e
CROSS JOIN anchor a
WHERE e.h3_cell IN (SELECT EXPLODE(H3_HEX_DISK(a.c, 2)));

-- Average a value across each cell and its neighbors up to k=2.
SELECT center,
       (SELECT AVG(value) FROM analytics.curated.h3_events_res9 e
        WHERE e.h3_cell IN (SELECT EXPLODE(H3_HEX_DISK(center, 2)))) AS smoothed_value
FROM analytics.curated.h3_events_res9;

-- A k-disk covers roughly k * edge_length meters from the center.
SELECT
  c,
  3 * H3_EDGE_LENGTH(c) AS approx_k3_radius_m
FROM (SELECT H3_LATLNG_TO_CELL(35.6762, 139.6503, 9) AS c);

Pitfalls

The disk is a set of cells, not a circular region. The covered area is a hex-tiling approximation of a circle; near pentagons it is noticeably asymmetric.
The disk count grows as 3k(k+1)+1 which is ~7 at k=1, ~37 at k=3, and ~331 at k=10. Large k values at fine resolutions generate huge arrays; combine smaller k with a coarser resolution when possible.
A disk at a pentagon center has 6 cells at k=1 (center + 5 neighbors), not 7. Code that assumes every k=1 disk has exactly 7 cells is incorrect for the twelve pentagons at each resolution.
H3_HEX_DISK returns a filled disk; H3_HEX_RING returns only the outermost ring at distance k. Mixing them up produces off-by-orders-of-magnitude errors.
The result exceeds the internal cap (approximately one million cells) for very large k. Plan queries so that k * edge_length stays within your real analysis radius.