Categories:

Geospatial functions

H3_COVERAGE

Returns an array of IDs (as INTEGER values) identifying the minimal set of H3 cells that completely cover a shape (specified by a GEOGRAPHY object).

See also:

H3_COVERAGE_STRINGS , H3_TRY_COVERAGE , H3_POLYGON_TO_CELLS

Syntax

H3_COVERAGE( <geography_expression> , <target_resolution> )

Arguments

geography_expression

A GEOGRAPHY object.

target_resolution

An INTEGER between 0 and 15 (inclusive) specifying the H3 resolution that you want to use for the returned H3 cells.

Specifying any other INTEGER value results in an error.

Returns

Returns an ARRAY of INTEGER values for the IDs of the minimal set of H3 cells that have completely cover the specified input shape.

Usage notes

  • The function uses spherical approximation, which treats points on the Earth’s surface as if they were connected by arcs, rather than straight lines. If you need a planar approximation, use H3_POLYGON_TO_CELLS instead.
  • A cell is included in the result set if its boundary intersects the input shape.
  • When you apply FLATTEN to the ARRAY returned by the function, cast each value explicitly to an integer.
  • If it isn’t possible to compute the coverage for an invalid GEOGRAPHY object, the function returns NULL. For more information, see Effects on GEOGRAPHY objects.
  • If the number of H3 cells that cover the input shape exceeds the allowed limit, the function reports an error. To return NULL instead of reporting an error, use H3_TRY_COVERAGE.

Examples

The following example returns an ARRAY of the IDs that identify the minimal set of H3 cells that completely cover the specified Polygon.

SELECT H3_COVERAGE(
  TO_GEOGRAPHY(
    'POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'),
  8) AS set_of_h3_cells_covering_polygon;

+----------------------------------+
| SET_OF_H3_CELLS_COVERING_POLYGON |
|----------------------------------|
| [                                |
|   613196571542028287,            |
|   613196571548319743,            |
|   613196571598651391,            |
|   613196571539931135,            |
|   613196571560902655,            |
|   613196571550416895             |
| ]                                |
+----------------------------------+