メインコンテンツまでスキップ

h3_try_tessellateaswkb function

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 16.3 and above

This function behaves the same as h3_tessellateaswkb, but returns NULL instead of an error if the function fails to produce a tesselation. It returnstessellation of the input geography using H3 cells at the specified resolution. The tessellation is represented by an ARRAY of structs, each representing an element of the tessellation. Each element of the tessellation consists of a H3 cell ID (BIGINT), a Boolean value indicating whether the input geography fully covers the cell, and a BINARY value corresponding to the WKB description of the intersection of the input geography with the H3 cell.

Syntax​

h3_try_tessellateaswkb ( geographyExpr, resolutionExpr )

Arguments​

  • geographyExpr: A BINARY or STRING expression representing a 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, with a value between 0 and 15 inclusive, specifying the resolution for the H3 cell IDs.

Returns​

An ARRAY of named structs with three fields of type BIGINT, BOOLEAN, and BINARY, named cellid, core, and chip, respectively, representing the tessellation of the input geography with H3 cells at the specified resolution.

The first field in the struct is an H3 cell ID represented as a BIGINT. The second field is a BOOLEAN indicating whether the cell is a core cell. A core cell is one that is entirely contained within the input geography. Its intersection with the input is the full cell. The value is true for core cells and false otherwise. The third field is a BINARY value representing the WKB description of the geography that is the intersection of the input geography and the H3 cell. The returned H3 cells collectively form a minimal covering set of the input geography. The geographies, corresponding to the returned WKB descriptions, collectively form a tessellation (decomposition) of the input geography.

The function returns NULL if any 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, linestring, polygon, multipoint, multilinestring, or 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 point, linestring, polygon, multipoint, multilinestring, or multipolygon. The dimension of the input geography can be 2D, 3DZ, 3DM, or 4D. The function returns NULL if the first argument corresponds to an invalid WKB, WKT, or GeoJSON or does not represent a point, linestring, polygon, multipoint, multilinestring, or multipolygon. The function returns NULL if it fails to produce a tessellation.

Error conditions​

Examples​

SQL
> SELECT h3_h3tostring(cellid), core, hex(chip) FROM (SELECT inline(h3_tessellateaswkb('MULTIPOINT(20 0,20 10,40 30)', 0))) ORDER BY 1
  802dfffffffffff     false 010100000000000000000044400000000000003E40
  806bfffffffffff     false 010400000002000000010100000000000000000034400000000000000000010100000000000000000034400000000000002440

-- Feeding an empty geometry collection in GeoJSON format (geometry collections are not supported).
> SELECT h3_tessellateaswkb('{"type":"GeometryCollection","geometries":[]}', 2)
  null

-- Feeding an invalid WKB (invalid endianness value)
> SELECT h3_tessellateaswkb(unhex('020700000000'), 2)
  null

-- Feeding an invalid polygon in WKT (polygon is not closed)
> SELECT h3_tessellateaswkb('POLYGON((-122.4194 37.7749,-118.2437 34.0522,-74.0060 40.7128,-74.0060 40.7128))', 2)
  null

-- Resolution is out of range.
> SELECT h3_tessellateaswkb('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 SQLSTATE: 22023
に最終更新