Partager via

Fonction h3_tessellateaswkb

  • Article

S’applique à : coche marquée oui Databricks SQL case marquée oui Databricks Runtime 14.2 et versions ultérieures

Retourne un pavage de la géographie d’entrée à l’aide des cellules H3, à la résolution spécifiée. Le pavage est représenté par un ARRAY (tableau) de structs, chacun représentant un élément du pavage. Chaque élément du pavage se compose d’un ID de cellule H3 (représenté sous la forme d’un entier long), d’une valeur booléenne indiquant si la géographie d’entrée couvre complètement la cellule et d’une valeur BINARY correspondant à la description WKB de l’intersection de la géographie d’entrée avec la cellule H3.

Les cellules H3 retournées forment collectivement un ensemble minimal d’hexagones ou de pentagones, à la résolution spécifiée, qui couvrent complètement la géographie d’entrée. Les géographies retournées (via leurs représentations WKB) forment un pavage de la géographie d’entrée.

Syntaxe

h3_tessellateaswkb ( geographyExpr, resolutionExpr )

Arguments

  • geographyExpr : expression BINARY ou STRING représentant une géographie dans WKB, WKT ou GeoJSON. La géographie doit avoir des coordonnées de longitude et de latitude en degrés faisant référence au système de référence de coordonnées WGS84.
  • resolutionExpr: Une expression INT, avec une valeur comprise entre 0 et 15 inclus, spécifiant la résolution des ID de cellule H3.

Retours

Un ARRAY de structs nommés avec trois champs de type BIGINT, BOOLEAN et BINARY, nommés respectivement cellid, core et chip, et représentant le pavage de la géographie d’entrée avec des cellules H3 à la résolution spécifiée.

Le premier champ du struct est un ID de cellule H3 (représenté sous la forme d’un entier long). Le deuxième champ du struct est une valeur booléenne indiquant si la cellule H3 est une cellule principale. Si tel est le cas, la valeur du champ est true. Dans le cas contraire, la valeur du champ est false. Une cellule principale est une cellule H3 entièrement couverte par la géographie d’entrée (autrement dit, son intersection avec la géographie d’entrée correspond à la cellule elle-même). Le troisième champ est une valeur BINARY représentant la description WKB de la géographie qui correspond à l’intersection de la géographie d’entrée et de la cellule H3. Les cellules H3 retournées forment collectivement un ensemble de couverture minimal de la géographie d’entrée. Les géographies, qui correspondent aux descriptions WKB retournées, forment collectivement un pavage (décomposition) de la géographie d’entrée.

La fonction retourne NULL si l’une des expressions d’entrée est NULL. Si le premier argument d’entrée est de type BINARY, la valeur d’entrée est censée être la description WKB d’un point, d’une ligne, d’un polygone, de plusieurs points, de plusieurs lignes ou de plusieurs polygones. Si le premier argument d’entrée est de type STRING, la valeur d’entrée est censée être la description WKT ou GeoJSON d’un point, d’une ligne, d’un polygone, de plusieurs points, de plusieurs lignes ou de plusieurs polygones. La dimension de la géographie d’entrée peut être au format 2D, 3DZ, 3DM ou 4D.

Conditions d’erreur

  • Si geographyExpr est de type BINARY, et si la valeur est un WKB non valide ou si elle représente une collection de géométries, la fonction retourne WKB_PARSE_ERROR.
  • Si geographyExpr est de type STRING, et si la valeur est un WKT non valide ou si elle représente une collection de géométries, la fonction retourne WKT_PARSE_ERROR.
  • Si geographyExpr est de type STRING, et si la valeur est un GeoJSON non valide ou si elle représente une collection de géométries, la fonction retourne GEOJSON_PARSE_ERROR.
  • Si resolutionExpr est inférieure à 0 ou supérieure à 15, la fonction retourne H3_INVALID_RESOLUTION_VALUE.

Exemples

> 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)
  [GEOJSON_PARSE_ERROR] Error parsing GeoJSON: Invalid or unsupported type '"GeometryCollection"' at position 9 SQLSTATE: 22023

-- Feeding an invalid WKB (invalid endianness value)
> SELECT h3_tessellateaswkb(unhex('020700000000'), 2)
  [WKB_PARSE_ERROR] Error parsing WKB: Invalid byte order 2 at position 1 SQLSTATE: 22023

-- 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)
  [WKT_PARSE_ERROR] Error parsing WKT: Found non-closed ring at position 80 SQLSTATE: 22023

-- 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