h3_polyfillash3
function
Applies to: Databricks SQL Databricks Runtime 11.3 LTS and above
Returns an ARRAY of H3 cell IDs (represented as BIGINT) corresponding to hexagons or pentagons, of the specified resolution, that are contained by the input areal geography.
Arguments
geographyExpr
: A BINARY or STRING expression representing an areal geography (polygon or multipolygon) in WKB, WKT, or GeoJSON. The geography is expected to have longitude and latitude coordinates in degrees that refer to the WGS84 coordinate reference system.resolutionExpr
: An INT expression, whose value is expected to be between0
and15
inclusive, specifying the resolution for the H3 cell IDs.
Returns
An ARRAY of BIGINT values corresponding to the H3 cell IDs, of the specified resolution, that are contained by the input areal geography.
The function returns NULL if any one of the input expressions is NULL. If the first input argument is of type BINARY, the input value is expected to be the WKB description of a polygon or a multipolygon. If the first input argument is of type STRING, the input value is expected to be either the WKT or the GeoJSON description of a polygon or a multipolygon. The dimension of the input polygon or multipolygon can be 2D, 3DZ, 3DM, or 4D.
Error conditions
If
geographyExpr
is of type BINARY and the value is either an invalid WKB or does not represent a polygon or multipolygon, the function returns WKB_PARSE_ERROR.If
geographyExpr
is of type STRING and the value is either an invalid WKT or does not represent a polygon or multipolygon, the function returns WKT_PARSE_ERROR.If
geographyExpr
is of type STRING and the value is either an invalid GeoJSON or does not represent a polygon or multipolygon, the function returns GEOJSON_PARSE_ERROR.If
resolutionExpr
is smaller than0
or larger than15
, the function returns H3_INVALID_RESOLUTION_VALUE.
Examples
-- Simple example where the input is a triangle in WKT format.
> SELECT h3_polyfillash3('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-122.4194 37.7749))', 2)
[586146350232502271,586147449744130047,586198577034821631,586152397546455039,586199676546449407,586153497058082815,586142501941805055,586201325813891071]
-- Simple example where the input is a triangle in hexadecimal WKB format.
> SELECT h3_polyfillash3(unhex('0103000000010000000400000050fc1873d79a5ec0d0d556ec2fe342404182e2c7988f5dc0f46c567dae064140aaf1d24d628052c05e4bc8073d5b444050fc1873d79a5ec0d0d556ec2fe34240'), 2)
[586146350232502271,586147449744130047,586198577034821631,586152397546455039,586199676546449407,586153497058082815,586142501941805055,586201325813891071]
-- Feeding an empty linestring in GeoJSON format (as opposed to a polygon or multipolygon).
> SELECT h3_polyfillash3('{"type":"LineString","coordinates":[]}', 2)
[GEOJSON_PARSE_ERROR] Error parsing GeoJSON: Invalid or unsupported type '"LineString"' at position 9
-- Feeding an invalid WKB (invalid endianness value)
> SELECT h3_polyfillash3(unhex('020700000000'), 2)
[WKB_PARSE_ERROR] Error parsing WKB: Invalid byte order 2 at position 1
-- Feeding an invalid polygon in WKT (polygon is not closed)
> SELECT h3_polyfillash3('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-74.0060 40.7128))', 2)
[WKT_PARSE_ERROR] Error parsing WKT: Found non-closed ring at position 80
-- Resolution is out of range.
> SELECT h3_polyfillash3('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-122.4194 37.7749))', 16)
[H3_INVALID_RESOLUTION_VALUE] H3 resolution 16 must be between 0 and 15, inclusive