H3_GRID_PATH

Return the array of H3 cells on the shortest grid path from one cell to another.

Category: h3Returns: ARRAY<BIGINT>Dialect: Standard

Syntax

H3_GRID_PATH(cell1, cell2)

Description

## Overview Returns an ordered array of H3 cells that form the shortest grid path between the two input cells. The path is inclusive of both endpoints, so its length equals the grid distance plus one. Adjacent entries in the array share a hex edge; the full array traces a corridor of neighboring cells. Use it to build heatmap corridors, to annotate routes with per-cell statistics, to visualize connectivity between two locations at a chosen resolution, and to seed animation or interpolation over a spatial path. ## Behavior - Returns an ARRAY<BIGINT> in order from cell1 to cell2, inclusive. - Array size equals H3_GRID_DISTANCE(cell1, cell2) + 1. - Returns NULL if the cells are at different resolutions. - Returns NULL if either cell is NULL or invalid. - May return NULL when the shortest path crosses a pentagon boundary that cannot be traced by simple hex steps. - If cell1 equals cell2, returns an array of one element (that cell). - The result is capped at approximately 1,000,000 cells to protect against OOM; very long paths return NULL. - Deterministic: the same pair always returns the same path. ## H3 resolution reference | Res | Average edge length | Cells per km of path | | --- | --- | --- | | 7 | 1.22 km | ~0.82 | | 8 | 461 m | ~2.2 | | 9 | 174 m | ~5.8 | | 10 | 65.9 m | ~15 | | 12 | 9.4 m | ~106 | ## Compatibility - Follows the standard H3 hierarchical hex grid specification for grid path computation.

Parameters

Name	Type	Description
`cell1`		Specifies the starting H3 cell. Must be a valid H3 cell at the same resolution as cell2.
`cell2`		Specifies the ending H3 cell. Must be a valid H3 cell at the same resolution as cell1.

Examples

-- Returns an ordered array including both endpoints.
SELECT H3_GRID_PATH(
  H3_LATLNG_TO_CELL(40.7580, -73.9855, 9),
  H3_LATLNG_TO_CELL(40.7614, -73.9776, 9)
) AS path;

-- The path array has N+1 cells for a grid distance of N.
SELECT
  H3_GRID_DISTANCE(a, b) AS steps,
  SIZE(H3_GRID_PATH(a, b)) AS path_cells
FROM (
  SELECT H3_LATLNG_TO_CELL(48.8566, 2.3522, 9) AS a,
         H3_LATLNG_TO_CELL(48.8606, 2.3376, 9) AS b
);

-- Explode the path and join on each cell to retrieve time-of-day stats.
SELECT ord, step_cell, h.events
FROM (
  SELECT POSEXPLODE(H3_GRID_PATH(
    H3_LATLNG_TO_CELL(40.7580, -73.9855, 9),
    H3_LATLNG_TO_CELL(40.7831, -73.9712, 9)
  )) AS (ord, step_cell)
) p
LEFT JOIN analytics.curated.h3_hourly h
  ON h.h3_cell = p.step_cell AND h.hour_utc = 12;

-- Dump path cells with their WKT boundary for a simple map export.
SELECT step_cell,
       H3_CELL_TO_BOUNDARY(step_cell) AS boundary_wkt
FROM (
  SELECT EXPLODE(H3_GRID_PATH(
    H3_LATLNG_TO_CELL(51.5074, -0.1278, 9),
    H3_LATLNG_TO_CELL(51.5150, -0.1419, 9)
  )) AS step_cell
);

-- Paths that would have to cross a pentagon distortion may return NULL.
SELECT H3_GRID_PATH(pentagon_neighbor_a, pentagon_neighbor_b) AS path
FROM diagnostics.h3_pentagon_pairs
LIMIT 1;

Pitfalls

Both cells must be at the same resolution. Different resolutions return NULL with no explicit error; always confirm resolution with H3_GET_RESOLUTION before calling.
Paths that cross a pentagon cell may return NULL. Handle NULL explicitly in downstream code, especially for long paths at fine resolutions where the chance of encountering a pentagon grows.
The array length grows linearly with grid distance. At resolution 12 a 1 km path contains over 100 cells; at resolution 15 it contains roughly 2,000. Do not request paths between far-apart cells at very fine resolutions.
The shortest grid path is not unique. The specific sequence returned is deterministic but may differ from the shortest path you would draw geometrically.
Grid path distance is measured in hex steps, not meters. Convert with H3_EDGE_LENGTH when a physical distance is needed.