Categories:

Geospatial functions

H3_TRY_COVERAGE

A special version of H3_COVERAGE that returns NULL if an error occurs when it attempts to return 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> )
Copy

Arguments

geography_expression

A GEOGRAPHY object.

target_resolution

An INTEGER between 0 and 15 (inclusive) specifying the H3 resolution (https://h3geo.org/docs/core-library/restable) 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 function cannot perform a successful calculation, returns NULL without reporting an error.

Usage notes

See H3_COVERAGE for the usage notes.

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;
Copy
+----------------------------------+
| SET_OF_H3_CELLS_COVERING_POLYGON |
|----------------------------------|
| NULL                             |
+----------------------------------+

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

Language: English