ST_AsMVTGeom function for geographic grid to geometric object conversion - PolarDB

Transforms a geographic grid object into the coordinate space of a Mapbox Vector Tile (MVT), producing the geometry input required by ST_AsMVT to generate the final MVT binary.

Syntax

geometry ST_AsMVTGeom(geomgrid grid, geometry bounds, int4 extent, int4 buffer, boolean clip_geom);
geometry ST_AsMVTGeom(h3grid grid, geometry bounds, int4 extent, int4 buffer, boolean clip_geom);

Return value

Returns a geometry object in the tile coordinate system.

Parameters

Parameter	Description	Default
`grid`	The geomgrid or H3 geographic grid object to transform into MVT coordinate space.	—
`bounds`	The bounding box of the tile, excluding the buffer. Must be a `geometry` type (not `Box2D`).	—
`extent`	The tile size in the tile coordinate system, as defined by the MVT specification.	4096
`buffer`	The buffer size in the tile coordinate system.	256
`clip_geom`	Specifies whether to clip the grid geometry at the tile boundary.	true

Usage notes

The bounds parameter type is geometry, not Box2D. Unlike the standard ST_AsMVTGeom variant whose tile boundary type is Box2D, this variant uses geometry for the bounds parameter.
The output coordinate system is determined by the bounds value. Use ST_TileEnvelope to generate bounds—it produces a correctly projected bounding box for the given tile coordinates.
If you generate bounds by any other method, specify the Spatial Reference Identifier (SRID) explicitly using the SRID=<srid>; prefix in the geometry string (for example, 'SRID=4326;POLYGON(...)').

Examples

Use ST_TileEnvelope to generate bounds (recommended)

This example transforms a geomgrid object using the tile envelope for the world tile at zoom level 0. The bounds SRID comes from ST_TileEnvelope, so no explicit SRID is needed.

SELECT ST_AsMVTGeom('010200040000'::geomgrid, ST_TileEnvelope(0, 0, 0));

Output:

0103000020110F000001000000050000000000000000D8A2400000000000FC99400000000000D8A240000000000000A040000000000000A040000000000000A040000000000000A0400000000000FC99400000000000D8A2400000000000FC9940

Transform bounds to SRID 4326

When the data is in WGS 84 (SRID 4326), transform the tile envelope to match before passing it as bounds.

SELECT ST_AsMVTGeom('010200040000'::geomgrid, ST_Transform(ST_TileEnvelope(0, 0, 0), 4326));

Output:

0103000020E610000001000000050000000000000000D8A2400000000000F493400000000000D8A240000000000000A040000000000000A040000000000000A040000000000000A0400000000000F493400000000000D8A2400000000000F49340

Override extent, buffer, and clip_geom

This example uses a smaller tile extent (1024), a smaller buffer (128), and disables geometry clipping at the tile boundary.

SELECT ST_AsMVTGeom('010200040000'::geomgrid, ST_Transform(ST_TileEnvelope(0, 0, 0), 4326), 1024, 128, false);

Output:

0103000020E610000001000000050000000000000000D882400000000000F073400000000000D8824000000000000080400000000000008040000000000000804000000000000080400000000000F073400000000000D882400000000000F07340

Use an H3 grid object with ST_TileEnvelope

This example uses an H3 grid cell (resolution 5, centered near latitude 20.5, longitude 128.2) and the world tile envelope as bounds.

SELECT ST_AsMVTGeom(ST_H3FromLatLng(20.5, 128.2, 5), ST_TileEnvelope(0, 0, 0));

Output:

0103000020110F00000100000006000000000000000064AB400000000000449C40000000000066AB400000000000489C40000000000066AB4000000000004C9C40000000000062AB4000000000004C9C40000000000062AB400000000000489C40000000000064AB400000000000449C40

Use an H3 grid object with an explicit SRID bounds

When you construct bounds manually rather than using ST_TileEnvelope, specify the SRID in the geometry string. This example uses the full-earth bounding polygon in WGS 84.

SELECT ST_AsMVTGeom(ST_H3FromLatLng(20.5, 128.2, 5), 'SRID=4326;POLYGON((-180 -85,-180 85, 180 85, 180 -85, -180 -85))');

Output:

0103000020E61000000100000007000000000000000064AB400000000000449840000000000066AB400000000000489840000000000066AB400000000000509840000000000064AB400000000000549840000000000062AB400000000000549840000000000062AB4000000000004C9840000000000064AB400000000000449840

What's next

ST_AsMVT: Aggregates the output of ST_AsMVTGeom into a binary MVT tile.
ST_TileEnvelope: Generates a tile bounding box for a given zoom/x/y tile coordinate.
ST_H3FromLatLng: Creates an H3 grid cell from a latitude/longitude coordinate and resolution level.