`h3_pointash3` function

Article
05/27/2024

Returns the H3 cell ID (as a BIGINT) corresponding to the provided point at the specified resolution.

Applies to: check marked yes Databricks SQL preview Databricks Runtime 11.3 LTS and above

Syntax

h3_pointash3 ( geographyExpr, resolutionExpr )

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 between 0 and 15 inclusive, specifying the resolution for the H3 cell ID.

Returns

Returns the H3 cell ID (as a BIGINT) 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 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 than 0 or larger than 15, the function returns H3_INVALID_RESOLUTION_VALUE.

Examples

-- Simple example.
> SELECT h3_pointash3('POINT(100 45)', 6)
  604116085645508607

-- The H3 cell ID for the Golden Gate Bridge at resolution 13.
> SELECT h3_pointash3('POINT(-122.4783 37.8199)', 13)
  635714569676958015

-- The function returns NULL if the input is the empty point.
> SELECT h3_pointash3('{"type":"Point","coordinates":[]}', 15)
  null

-- Feeding a multipoint in WKT format instead of a point.
> SELECT h3_pointash3('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_pointash3('{"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_pointash3(unhex('0201000000516b9a779c9e5ec0c5feb27bf2e84240'), 2)
  [WKB_PARSE_ERROR] Error parsing WKB: Invalid byte order 2 at position 1

-- Resolution is out of range.
> SELECT h3_pointash3('POINT(-122.4783 37.8199)', 16)
  [H3_INVALID_RESOLUTION_VALUE] H3 resolution 16 must be between 0 and 15, inclusive

h3_pointash3 function