h3_pointash3string
function
Returns the H3 cell ID (as a STRING) corresponding to the provided point at the specified resolution.
Applies to: Databricks SQL preview Databricks Runtime 11.3 LTS and above
Arguments
geographyExpr
: A BINARY or STRING expression representing a point geography 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 ID.
Returns
Returns the H3 cell ID (as a STRING) corresponding to the provided point at the specified resolution.
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](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry#Well-known_binary) description of a point. 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 point. The dimension of the input point can be 2D, 3DZ, 3DM, or 4D. The longitude and latitude values in the WKB, WKT, or GeoJSON description are expected to be in the WGS84 coordinate reference system. The function returns NULL if the first input corresponds to the empty point.
Error conditions
If
geographyExpr
is of type BINARY and the value is either an invalid WKB or does not represent a point, 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 point, 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 point, the function returns GEOJSON_PARSE_ERROR.If
resolutionExpr
is smaller than0
or larger than15
, the function returns H3_INVALID_RESOLUTION_VALUE.
Examples
-- Simple example.
> SELECT h3_pointash3string('POINT(100 45)', 6)
86240610fffffff
-- The H3 cell ID for the Golden Gate Bridge at resolution 13.
> SELECT h3_pointash3string('POINT(-122.4783 37.8199)', 13)
8d283087022a93f
-- The function returns NULL if the input is the empty point.
> SELECT h3_pointash3string('{"type":"Point","coordinates":[]}', 15)
null
-- Feeding a multipoint in WKT format instead of a point.
> SELECT h3_pointash3string('MULTIPOINT(100 45)', 6)
[WKT_PARSE_ERROR] Error parsing WKT: Invalid or unsupported type 'MULTIPOINT' at position 1
-- Feeding an invalid GeoJSON string ("type" value is not correct).
> SELECT h3_pointash3string('{"type":"POINT","coordinates":[]}', 15)
[GEOJSON_PARSE_ERROR] Error parsing GeoJSON: Invalid or unsupported type '"POINT"' at position 9
-- Feeding an invalid WKB (invalid endianness value)
> SELECT h3_pointash3string(unhex('0201000000516b9a779c9e5ec0c5feb27bf2e84240'), 2)
[WKB_PARSE_ERROR] Error parsing WKB: Invalid byte order 2 at position 1
-- Resolution is out of range.
> SELECT h3_pointash3string('POINT(-122.4783 37.8199)', 16)
[H3_INVALID_RESOLUTION_VALUE] H3 resolution 16 must be between 0 and 15, inclusive