H3_LATLNG_TO_CELL

Convert a latitude and longitude pair to the H3 cell index that contains the point at a given resolution.

Category: h3Returns: BIGINTDialect: Standard

Syntax

H3_LATLNG_TO_CELL(lat, lng, resolution)

Description

## Overview Returns the 64-bit H3 cell index that contains the given latitude and longitude at the specified resolution. The H3 hierarchical hex grid tiles the globe with hexagons (plus twelve pentagons at fixed locations) arranged so that every point on Earth belongs to exactly one cell at every resolution from 0 to 15. This function is the entry point for most H3 pipelines: raw coordinates go in, a deterministic integer key comes out, and that key drives bucketing, joins, aggregation, and partition pruning. Use this function when you want to convert streaming or batched point data into a discrete grid key. Because cell IDs are stable and hierarchical, you can pre-compute cells at several resolutions and then aggregate, join, or prefilter at whichever resolution fits the query. ## Behavior - Returns a BIGINT cell ID suitable for equality joins, GROUP BY, and indexing. - Returns NULL if latitude is outside [-90, 90], longitude is outside [-180, 180], or resolution is outside [0, 15]. - Returns NULL if any argument is NULL. - The mapping from (lat, lng, resolution) to cell is deterministic and reproducible across engines that implement the standard H3 library. - Points exactly on a cell boundary are assigned deterministically to one of the adjacent cells; the choice is stable but implementation-defined. - Resolutions differ by a factor of 7 in cell count; moving one level finer multiplies the number of cells covering the same area by approximately 7. - The output is a uint64 rendered as BIGINT. Use H3_CELL_TO_STRING to get the canonical 15 hex-digit string form for logging or APIs. ## H3 resolution reference | Res | Average edge length | Average hex area | Typical use | | --- | --- | --- | --- | | 0 | 1,107 km | 4.25 million km^2 | Continent | | 4 | 22.6 km | 1,770 km^2 | State or province | | 7 | 1.22 km | 5.16 km^2 | City | | 9 | 174 m | 0.11 km^2 | Neighborhood | | 12 | 9.4 m | 307 m^2 | Building | | 15 | 0.5 m | 0.9 m^2 | Sub-meter | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for cell indexing. A cell produced here can be read, compared, and navigated by any engine that implements the same specification. - Uses WGS 84 decimal degrees. There is no SRID argument.

Parameters

Name	Type	Description
`lat`		Specifies the WGS 84 latitude of the point in decimal degrees. Valid range: -90 (south pole) to 90 (north pole). Values outside this range cause the function to return NULL.
`lng`		Specifies the WGS 84 longitude of the point in decimal degrees. Valid range: -180 to 180, where negative values are west of the prime meridian.
`resolution`		Specifies the H3 hierarchy resolution of the target cell. Valid values are integers 0 through 15, where 0 is a continent-sized cell (average area 4.25 million km squared) and 15 is a sub-meter cell (average area 0.9 m squared). Most analytics workloads use resolutions 7 through 10.

Examples

-- San Francisco (37.7749, -122.4194) at resolution 9 (~174 m edge, ~0.11 km^2 cell).
SELECT H3_LATLNG_TO_CELL(37.7749, -122.4194, 9) AS cell_id;

-- Count ride pickups per resolution 8 cell for heatmap rendering.
SELECT
  H3_LATLNG_TO_CELL(pickup_lat, pickup_lng, 8) AS h3_cell,
  COUNT(*)                                      AS pickups
FROM mobility.raw.rides
GROUP BY H3_LATLNG_TO_CELL(pickup_lat, pickup_lng, 8)
ORDER BY pickups DESC;

-- Store the H3 cell alongside raw coordinates so downstream joins can use the cell as a bucket key.
CREATE TABLE telemetry.curated.device_events
USING DELTA
AS
SELECT
  event_id,
  device_id,
  latitude,
  longitude,
  H3_LATLNG_TO_CELL(latitude, longitude, 9) AS h3_res9,
  H3_LATLNG_TO_CELL(latitude, longitude, 7) AS h3_res7,
  event_time
FROM telemetry.raw.device_events;

-- Find all events within k=2 cells of a reference point at resolution 9.
WITH origin AS (
  SELECT H3_LATLNG_TO_CELL(40.7580, -73.9855, 9) AS center_cell
)
SELECT e.event_id
FROM telemetry.curated.device_events e
CROSS JOIN origin o
WHERE e.h3_res9 IN (SELECT EXPLODE(H3_HEX_DISK(o.center_cell, 2)));

-- Resolution 16 is out of range; the function returns NULL rather than erroring.
SELECT H3_LATLNG_TO_CELL(37.7749, -122.4194, 16) AS cell_id;

Pitfalls

Arguments are ordered (lat, lng, resolution). Passing longitude first silently produces a cell on the wrong side of the globe because both values are valid numbers in overlapping ranges.
Cells at different resolutions are not directly comparable. A resolution 8 cell and a resolution 9 cell covering the same point have different BIGINT values; use H3_CELL_TO_PARENT to bring them to a common resolution before comparing or joining.
The return value is a uint64 rendered as a BIGINT. Some drivers display it as a negative number when the high bit is set. Use H3_CELL_TO_STRING for stable display and interchange.
Resolution choice controls both accuracy and cell count. Going one level finer multiplies storage and join cardinality by about 7. Start at resolution 8 or 9 for city-scale work and only go finer if a downstream query needs it.
Points on cell boundaries are assigned deterministically but a point moved by a floating-point epsilon can land in a different cell. Do not compare H3 cells as a substitute for exact geometric containment.