H3_IS_VALID_CELL

Test whether a BIGINT value encodes a valid H3 cell index.

Category: h3Returns: BOOLEANDialect: Standard

Syntax

H3_IS_VALID_CELL(cell)

Description

## Overview Returns TRUE when the input BIGINT represents a real H3 cell according to the H3 specification. H3 cell IDs encode a mode, a resolution, a base cell, and a per-level digit string, all packed into 64 bits with specific invariants; most arbitrary 64-bit integers do not satisfy those invariants. This function performs the validation cheaply (bit-field checks) and is the right way to guard against corrupt, truncated, or spoofed H3 inputs at the edges of your pipeline. Use it whenever H3 cells enter your system from an untrusted source: ingests from third-party APIs, string parsing that did not validate, hand-constructed test data, and any place where cell IDs flow across a format boundary. ## Behavior - Returns a BOOLEAN. - Returns TRUE only if the bit pattern matches a valid H3 cell at a real resolution (0-15) with a real base cell. - Returns FALSE for arbitrary integers, zero, and malformed bit patterns. - Returns FALSE for NULL input (the function is not NULL-propagating; it behaves like IS NULL = FALSE). - The check is O(1): a handful of bit-field tests with no I/O. - Deterministic: the same input always returns the same result. ## Compatibility - Follows the standard H3 hierarchical hex grid specification for cell-index validity checks. A cell accepted here is accepted by every compliant H3 library.

Parameters

Name	Type	Description
`cell`		Specifies the candidate H3 cell index to validate. Any BIGINT is accepted; the function checks whether the bit pattern represents a real H3 cell at a real resolution.

Examples

-- Always TRUE for cells created by the library.
SELECT H3_IS_VALID_CELL(H3_LATLNG_TO_CELL(51.5074, -0.1278, 9)) AS valid;

-- Most BIGINTs are not valid H3 cells.
SELECT H3_IS_VALID_CELL(CAST(12345 AS BIGINT)) AS valid;

-- Drop rows whose cell IDs did not survive a flaky upstream conversion.
SELECT *
FROM imports.raw.h3_events
WHERE H3_IS_VALID_CELL(h3_cell);

-- String parsing may succeed for hex strings that do not represent real cells; double-check.
SELECT h3_str,
       H3_IS_VALID_CELL(H3_STRING_TO_CELL(h3_str)) AS valid
FROM imports.raw.h3_string_events;

-- Reject rows that do not carry a valid cell; preserves referential integrity downstream.
INSERT INTO analytics.curated.h3_events_res9
SELECT *
FROM imports.raw.h3_events
WHERE H3_IS_VALID_CELL(h3_cell)
  AND H3_GET_RESOLUTION(h3_cell) = 9;

Pitfalls

This function validates structure, not geographic reasonableness. A valid cell at the wrong resolution or in the wrong region will pass this check; combine with H3_GET_RESOLUTION or a region filter for stricter validation.
The function returns FALSE for NULL rather than NULL. Queries that want NULL propagation must test IS NULL explicitly.
H3_CELL_TO_STRING does NOT validate: you can format an arbitrary BIGINT as hex. Always validate the input first if the BIGINT came from an untrusted source.
H3_STRING_TO_CELL does validate: if it returns a non-NULL result, that result is a valid cell. Piping its output into H3_IS_VALID_CELL is redundant but harmless.
Cells produced by H3_LATLNG_TO_CELL, H3_CELL_TO_PARENT, H3_CELL_TO_CHILDREN, and H3_CELL_TO_CENTER_CHILD are always valid; you do not need to call this function on their outputs.