H3_CELL_TO_CHILDREN

Return all child cells of an H3 cell at a specified finer resolution.

Category: h3Returns: ARRAY<BIGINT>Dialect: Standard

Syntax

H3_CELL_TO_CHILDREN(cell, resolution)

Description

## Overview Returns an array of all H3 child cells that tile the given parent cell at a finer resolution. Hexagon parents have exactly 7 children at the next resolution and approximately 7^k children at resolution N+k. The twelve pentagon cells at each resolution have 6 children at the next resolution because one of the would-be children is absent at the icosahedron vertex. Use this function to expand a coarse-grained aggregate into its fine-grained tiles, to seed a downstream process that needs to operate at a finer resolution, or to enumerate the cells covered by a summary row. ## Behavior - Returns an ARRAY<BIGINT> of child cell IDs. Element order is deterministic but is not sorted numerically. - Returns NULL if the target resolution is coarser than or equal to the parent's resolution. - Returns NULL if the target resolution is outside [0, 15] or if the parent is NULL or invalid. - Hexagon parents produce 7 children one level down, 49 two levels down, and so on (7^k). - Pentagon parents produce 6 children at the next resolution because the icosahedron-vertex child does not exist; at deeper levels the pentagon line propagates through exactly one pentagon child per level. - The result is capped at approximately 1,000,000 cells; requesting more returns NULL to protect against OOM. - The union of children exactly tiles the parent cell (to within floating-point tolerance at the boundaries). ## H3 resolution reference | Res | Average edge length | Average hex area | | --- | --- | --- | | 0 | 1,107 km | 4.25 million km^2 | | 7 | 1.22 km | 5.16 km^2 | | 9 | 174 m | 0.11 km^2 | | 12 | 9.4 m | 307 m^2 | | 15 | 0.5 m | 0.9 m^2 | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for parent-child decomposition.

Parameters

Name	Type	Description
`cell`		Specifies the parent H3 cell index to expand. Must be a valid H3 cell.
`resolution`		Specifies the target finer resolution. Valid values are integers from the parent's resolution + 1 through 15. Coarser or equal resolutions return NULL.

Examples

-- A non-pentagon parent at resolution 7 has exactly 7 children at resolution 8.
SELECT H3_CELL_TO_CHILDREN(H3_LATLNG_TO_CELL(40.7128, -74.0060, 7), 8) AS children;

-- Approximately 7^2 = 49 children when descending 2 levels for a hexagon parent.
SELECT SIZE(H3_CELL_TO_CHILDREN(H3_LATLNG_TO_CELL(48.8566, 2.3522, 4), 6)) AS child_count;

-- For each resolution 6 summary row, emit one row per resolution 9 child cell.
SELECT s.parent_cell,
       c.child_cell,
       s.value
FROM spatial.curated.h3_summary_res6 s
LATERAL VIEW EXPLODE(H3_CELL_TO_CHILDREN(s.parent_cell, 9)) c AS child_cell;

-- Sum of child areas approximately equals parent area (to within numerical precision).
SELECT
  H3_CELL_AREA(parent) AS parent_area,
  (SELECT SUM(H3_CELL_AREA(c)) FROM UNNEST(H3_CELL_TO_CHILDREN(parent, 8)) AS c) AS children_area_sum
FROM (SELECT H3_LATLNG_TO_CELL(51.5074, -0.1278, 7) AS parent);

-- Asking for children at a coarser resolution returns NULL.
SELECT H3_CELL_TO_CHILDREN(H3_LATLNG_TO_CELL(51.5, -0.12, 9), 7) AS children;

Pitfalls

The child count grows as 7^k where k is the number of resolutions you descend. Going from resolution 7 to 13 produces roughly 117,649 children per parent; plan memory and query runtime accordingly.
Pentagon parents have 6 children, not 7. Code that hard-codes a multiplier of 7 will miscount the twelve pentagon cells at each resolution.
Results exceeding the internal cell limit return NULL rather than truncating. If you see NULL output unexpectedly, reduce the resolution gap or the fan-out.
The children array is not sorted. If you need a deterministic order for testing or diffing, apply an explicit ORDER BY or SORT step.
The target resolution must be finer than the parent. Passing an equal or coarser resolution returns NULL, not the parent itself.