H3_LATLNG_TO_CELL_FAST

Convert latitude and longitude to an H3 cell using a vectorized, multi-threaded batch path.

Category: h3Returns: BIGINTDialect: Standard

Syntax

H3_LATLNG_TO_CELL_FAST(lat, lng, resolution)

Description

## Overview Returns the H3 cell that contains the given point, computed through a vectorized, multi-threaded batch path that scales across CPU cores using a data-parallel work-stealing runtime. The numerical result is identical to H3_LATLNG_TO_CELL for every input; the difference is end-to-end throughput on large arrays. Use this function for high-volume ingest pipelines, heatmap bucketing over billions of rows, materialized spatial keys, and any workload where per-row cost matters. For single-row scalar calls or small batches the non-FAST variant is equally good, because the parallelism overhead does not amortize on tiny inputs. ## Behavior - Returns a BIGINT cell ID at the requested resolution. - Returns NULL if any argument is NULL, the coordinate is out of range, or the resolution is outside [0, 15]. - Produces results identical to H3_LATLNG_TO_CELL for every input; this is a pure throughput optimization. - Deterministic: the same input always returns the same output. - Accepts Int32, Int64, and UInt8 resolution arguments. - The output is a UInt64 surfaced as BIGINT. - Fastest when both lat and lng arguments are columnar arrays; the runtime schedules row ranges across worker threads. Mixed scalar/array or all-scalar inputs fall back to the standard path at the same speed as H3_LATLNG_TO_CELL. ## Performance - Typical speedup over H3_LATLNG_TO_CELL on multi-million row arrays: 5x to 10x, scaling with available cores. - On a single scalar input there is no meaningful speedup; use H3_LATLNG_TO_CELL for scalar calls to avoid unnecessary runtime setup. ## 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 - Produces cell IDs that conform to the standard H3 hierarchical hex grid specification. Cells returned by this function are bit-identical to cells returned by H3_LATLNG_TO_CELL and interoperate with every other H3 function.

Parameters

Name	Type	Description
`lat`		Specifies the WGS 84 latitude of the point in decimal degrees. Valid range: -90 to 90.
`lng`		Specifies the WGS 84 longitude of the point in decimal degrees. Valid range: -180 to 180.
`resolution`		Specifies the H3 hierarchy resolution of the target cell as an integer in the range 0 through 15.

Examples

-- Use the fast variant on billions of rows where pentagon-boundary correctness is not required.
SELECT event_id,
       H3_LATLNG_TO_CELL_FAST(latitude, longitude, 9) AS h3_res9
FROM telemetry.raw.device_events;

-- Resolution 8 is enough for most heatmaps and the _FAST path trims CPU time on large tables.
SELECT H3_LATLNG_TO_CELL_FAST(latitude, longitude, 8) AS h3_cell,
       COUNT(*)                                       AS event_count
FROM telemetry.raw.device_events
GROUP BY H3_LATLNG_TO_CELL_FAST(latitude, longitude, 8);

-- Pre-compute the cell at write time so downstream queries never repeat the work.
INSERT INTO analytics.curated.geo_events
SELECT *,
       H3_LATLNG_TO_CELL_FAST(lat, lng, 9) AS h3_res9
FROM analytics.raw.geo_events;

-- Away from the twelve pentagons the fast and exact variants match.
SELECT
  H3_LATLNG_TO_CELL_FAST(37.7749, -122.4194, 9) = H3_LATLNG_TO_CELL(37.7749, -122.4194, 9) AS equal_for_sf;

-- NULL in any argument yields NULL.
SELECT H3_LATLNG_TO_CELL_FAST(NULL, -122.4194, 9) AS cell_id;

Pitfalls

The speedup only materializes on columnar, batched inputs. On scalar calls or very small arrays, H3_LATLNG_TO_CELL is equally fast and simpler to reason about.
Coordinates outside [-90, 90] latitude or [-180, 180] longitude return NULL rather than wrapping. Validate and clamp upstream if your source data has out-of-range values.
Cells at different resolutions are not directly comparable. Use H3_CELL_TO_PARENT to align two cells at a shared resolution before equality-joining, or use H3_SPATIAL_JOIN_FAST which handles mixed resolutions automatically.
The resolution argument must be in [0, 15]. Supplying 16 or above returns NULL silently; validate the resolution once per pipeline rather than re-checking per row.
Although output is bit-identical to H3_LATLNG_TO_CELL, do not mix the two in equality joins on data that was indexed by different runs; use one function consistently per table to keep the write path deterministic.