Use ST_AsMVTEx to filter vector elements and reduce MVT size - ApsaraDB RDS

ST_AsMVTEx serves the same purpose as ST_AsMVT and returns a binary Mapbox Vector Tile (MVT) representation of a set of rows. ST_AsMVTEx extends ST_AsMVT with two additional parameters: scale_factor to filter out vector elements that have little visual impact, and mvt_size_limit to cap the total number of vector elements per tile. Both reduce tile size and improve rendering performance.

Syntax

bytea ST_AsMVTEx(anyelement row);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor, int4 mvt_size_limit);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor, int4 mvt_size_limit, text name);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor, int4 mvt_size_limit, text name, int4 extent);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor, int4 mvt_size_limit, text name, int4 extent, text geom_name);
bytea ST_AsMVTEx(anyelement row, int4 scale_factor, int4 mvt_size_limit, text name, int4 extent, text geom_name, text feature_id_name);

Return value

Returns a bytea value containing a binary MVT representation that corresponds to a tile layer. The tile content is determined by the set of input rows.

Parameters

Parameter	Type	Default	Description
`row`	`anyelement`	—	Row data with at least one geometry column.
`scale_factor`	`int4`	`1`	Controls how aggressively vector elements are filtered. Valid values: `1` to `extent - 1`. Higher values filter more elements and produce a smaller tile.
`mvt_size_limit`	`int4`	`2147483647`	Maximum number of vector elements a tile can contain. If the element count after filtering still exceeds this limit, the system randomly discards the excess elements.
`name`	`text`	`default`	Name of the tile layer.
`extent`	`int4`	`4096`	Tile extent in screen space, as defined by the MVT specification.
`geom_name`	`text`	First geometry column	Name of the geometry column in the row data.
`feature_id_name`	`text`	—	Name of the Feature ID column. The Feature ID is not set for `NULL` or negative values. The first column that matches the name and has a valid type (`smallint`, `integer`, or `bigint`) is used as the Feature ID; any subsequent matching column is added as a property. JSON properties are not supported.

Usage notes

ST_AsMVTEx is not suitable for datasets that consist of large planes.

Warning

Setting extent to a very large value degrades system performance.

Examples

The examples below use the same dataset: one plane, one line, and 9,998 points.

-- Create a vector data table and insert one plane, one line, and 9,998 points.
CREATE TABLE example_table(id integer, geom Geometry);
INSERT INTO example_table(id, geom) VALUES
  (1, ST_MakeEnvelope(150, 75, 170, 80, 4326));
INSERT INTO example_table(id, geom) VALUES
  (2, ST_GeomFromText('LINESTRING(-160 -70, 160 -70)', 4326));
INSERT INTO example_table(id, geom)
SELECT i,
  ST_SetSRID(ST_MakePoint((random() * 20) + 150, (random() * 10) + 70), 4326)
FROM generate_series(3, 10000) i;

All examples use ST_AsMVTGeom to prepare geometries before passing them to ST_AsMVTEx.

Example 1: Set scale_factor to 1 (minimal filtering)

WITH mvtgeom AS
(
    SELECT ST_AsMVTGeom(geom, ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)) FROM example_table
    WHERE geom && ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)
)
SELECT length(ST_AsMVTEx(mvtgeom.*, 1)) FROM mvtgeom;

Output:

 length
--------
  54237
(1 row)

Example 2: Set scale_factor to 4 (more filtering, smaller tile)

WITH mvtgeom AS
(
    SELECT ST_AsMVTGeom(geom, ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)) FROM example_table
    WHERE geom && ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)
)
SELECT length(ST_AsMVTEx(mvtgeom.*, 4)) FROM mvtgeom;

Output:

 length
--------
  39211
(1 row)

Example 3: Add mvt_size_limit to cap elements at 100

WITH mvtgeom AS
(
    SELECT ST_AsMVTGeom(geom, ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)) FROM example_table
    WHERE geom && ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)
)
SELECT length(ST_AsMVTEx(mvtgeom.*, 4, 100)) FROM mvtgeom;

Output:

 length
--------
   1117
(1 row)

Example 4: Set tile resolution to 10000 x 10000 and layer name to layer_name

WITH mvtgeom AS
(
    SELECT ST_AsMVTGeom(geom, ST_Transform(ST_TileEnvelope(1, 1, 0), 4326), 10000) FROM example_table
    WHERE geom && ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)
)
SELECT length(ST_AsMVTEx(mvtgeom.*, 4, 100, 'layer_name', 10000)) FROM mvtgeom;

Output:

 length
--------
   1220
(1 row)

Example 5: Specify geometry column and Feature ID column

WITH mvtgeom AS
(
    SELECT ST_AsMVTGeom(geom, ST_Transform(ST_TileEnvelope(1, 1, 0), 4326), 10000) AS geom_field,
           id AS id_field
    FROM example_table
    WHERE geom && ST_Transform(ST_TileEnvelope(1, 1, 0), 4326)
)
SELECT length(ST_AsMVTEx(mvtgeom.*, 4, 100, 'layer_name', 10000, 'geom_field', 'id_field')) FROM mvtgeom;

Output:

 length
--------
   1520
(1 row)