H3_CONTAINS_FAST

Test whether a coarser H3 cell contains a finer H3 cell using a fast hierarchical prefix check.

Category: h3Returns: BOOLEANDialect: Standard

Syntax

H3_CONTAINS_FAST(parent_cell, child_cell)

Description

## Overview Returns TRUE if the second (child) cell is equal to the first (parent) cell or is one of its descendants in the H3 hierarchy. The test is implemented as a fast bit-level comparison on the H3 index structure: it walks the parent of the child cell up to the parent's resolution and compares. No geometric test is performed, which makes this operation orders of magnitude faster than point-in-polygon or polygon-in-polygon checks. Use this for hierarchical containment filtering, for pruning candidate rows before a slower exact spatial test, and for implementing region-based access controls on top of an H3-indexed table. ## Behavior - Returns a BOOLEAN. - Returns TRUE if parent_cell equals child_cell (self-containment) or parent_cell is an ancestor. - Returns FALSE if the child is at a coarser resolution than the parent, or if the two cells do not share an ancestor chain. - Returns NULL if either input is NULL. - Returns FALSE for invalid cell IDs (the test cannot succeed if inputs are not real H3 cells). - Equivalent to `H3_CELL_TO_PARENT(child_cell, H3_GET_RESOLUTION(parent_cell)) = parent_cell`, but much faster. - Pentagon hierarchy is respected: a pentagon parent correctly contains its (pentagon) descendants. ## H3 resolution reference | Res | Average edge length | Average hex area | | --- | --- | --- | | 0 | 1,107 km | 4.25 million km^2 | | 5 | 8.54 km | 253 km^2 | | 7 | 1.22 km | 5.16 km^2 | | 9 | 174 m | 0.11 km^2 | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for parent-child containment.

Parameters

Name	Type	Description
`parent_cell`		Specifies the candidate ancestor H3 cell at a coarser (numerically smaller) resolution. Must be a valid H3 cell.
`child_cell`		Specifies the candidate descendant H3 cell at an equal or finer (numerically greater or equal) resolution. Must be a valid H3 cell.

Examples

-- Resolution 5 parent; ask whether a resolution 9 cell over the same point is contained.
SELECT H3_CONTAINS_FAST(
  H3_LATLNG_TO_CELL(40.7128, -74.0060, 5),
  H3_LATLNG_TO_CELL(40.7128, -74.0060, 9)
) AS is_contained;

-- London parent does not contain a Paris descendant.
SELECT H3_CONTAINS_FAST(
  H3_LATLNG_TO_CELL(51.5074, -0.1278, 4),
  H3_LATLNG_TO_CELL(48.8566, 2.3522, 9)
) AS london_contains_paris;

-- Keep only finer cells that descend from a specified coarse region cell.
SELECT event_id, h3_res9
FROM analytics.curated.h3_events_res9
WHERE H3_CONTAINS_FAST(CAST(608500196905811967 AS BIGINT), h3_res9);

-- Fast pre-check narrows the rows before a slower ST_CONTAINS call.
SELECT *
FROM events e
WHERE H3_CONTAINS_FAST(region.h3_res7, H3_LATLNG_TO_CELL(e.lat, e.lng, 9))
  AND ST_CONTAINS(region.geom, ST_POINT(e.lng, e.lat));

Pitfalls

This is a hierarchical test, not a geometric test. It tells you whether the child descends from the parent in the H3 tree, not whether a point lies in a polygon.
The child cell must be at the same or a finer resolution than the parent. Passing a child at a coarser resolution returns FALSE.
The function does not verify that the inputs are valid H3 cells. Garbage-in produces FALSE rather than an error, which can mask bad input data; validate with H3_IS_VALID_CELL when needed.
For boundary-exact geometric containment (for example, is this point inside this polygon, regardless of H3 bucketing), pair this function with an exact spatial check such as ST_CONTAINS.
Pentagon cells share their pentagon property with all descendants; there are still twelve pentagon chains in the hierarchy and this function handles them correctly, but do not assume every descendant of a non-pentagon parent is non-pentagon. The pentagon line does not cross through non-pentagon parents.