Categories:: Geospatial functions

H3_TRY_COVERAGE¶

A special version of H3_COVERAGE that returns NULL instead of reporting an error when the number of H3 cells that cover a shape exceeds the allowed limit. The function 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).

Syntax¶

H3_TRY_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 or NULL.

If the function can perform a successful calculation, returns an array of INTEGER values for the IDs of the minimal set of H3 cells that completely cover the specified input shape.
If the number of H3 cells that cover the input shape exceeds the allowed limit, or if it isn’t possible to compute the coverage for an invalid GEOGRAPHY object, the function returns NULL without reporting an error.

Usage notes¶

For spherical approximation, cell inclusion, and flattening the returned array, see H3_COVERAGE.
If it isn’t possible to compute the coverage for an invalid GEOGRAPHY object, the function returns NULL. H3_COVERAGE also returns NULL in this case. 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 returns NULL without reporting an error. H3_COVERAGE reports an error in this case.

Examples¶

The following example attempts to return an array of IDs that identify the minimal set of H3 cells that completely cover a shape (specified by a GEOGRAPHY object). Because the array with the cells that cover the given hexagon at the given resolution exceeds the allowed size limit, the function returns NULL.

SELECT H3_TRY_COVERAGE(
  TO_GEOGRAPHY('POLYGON((-108.959 40.948,
                         -109.015 37.077,
                         -102.117 36.956,
                         -102.134 40.953,
                         -108.959 40.948))'
              ), 15) AS set_of_h3_cells_covering_polygon;

+----------------------------------+
| SET_OF_H3_CELLS_COVERING_POLYGON |
|----------------------------------|
| NULL                             |
+----------------------------------+

For examples that successfully return an array of IDs, see H3_COVERAGE.