Builds a vector pyramid for a spatial geometry data table, pre-tiling geometry data across zoom levels to accelerate map rendering at varying scales.
Syntax
boolean ST_BuildPyramid(cstring table, cstring geom, cstring fid, cstring config)Parameters
| Parameter | Description |
|---|---|
table | The name of the spatial geometry data table. |
geom | The name of the geometry column. |
fid | The name of the element ID field. |
config | Pyramid build options, specified as a JSON string. See Config fields for the full list of supported fields. |
Config fields
The config parameter accepts a JSON object with the following fields.
| Field | Type | Default | Description |
|---|---|---|---|
name | string | Same as the table name | The name of the pyramid. |
parallel | int | 0 | The maximum number of tasks to run in parallel. Set to 0 for no limit. Requires the max_prepared_transactions parameter to be configured. |
tileSize | int | 1024 | The tile size. Must be greater than 0 and less than 4096. |
tileExtend | int | 8 | The tile extension size of the pyramid. Must be greater than 0. |
userExtent | array[double] | null | The bounding box that constrains pyramid generation, specified as [minx, miny, maxx, maxy]. Set to [] to use no bounding box. |
splitSize | int | 10000 | The maximum number of elements per index node. A larger value produces a sparser pyramid. |
maxLevel | int | 16 | The maximum number of zoom levels. Valid values: 0–20. |
sourceSRS | int | -1 | The Spatial Reference Identifier (SRID) of the source data. Set to -1 to read the SRID from the table metadata. |
destSRS | int | 3857 | The EPSG code for the output tile coordinate system. Supported values: 3857 (EPSG:3857, Web Mercator) and 4326 (EPSG:4326, WGS84). |
buildRules | array[object] | null | Per-zoom-level rules for pyramid generation. See buildRules fields. |
buildRules fields
Each object in the buildRules array applies a rule to a set of zoom levels. Rules let you control data density per level — for example, filter out minor features at low zoom levels to reduce data volume, and include full attribute detail at high zoom levels to support map interactivity.
| Field | Type | Description |
|---|---|---|
level | array[int] | The zoom levels to which the rule applies. |
value | object | The rule definition. Contains the fields below. |
value.filter | string | A PostgreSQL filter expression to include only matching features. |
value.attrFields | array[string] | The attribute fields to include in the Mapbox Vector Tile (MVT) output. |
value.merge | array[string] | Filter conditions used to group data records. |
Config example
{
"name": "hello",
"parallel": 4,
"tileSize": 512,
"tileExtend": 8,
"userExtent": [-180, -90, 180, 90],
"splitSize": 5000,
"maxLevel": 16,
"destSRS": 3857,
"buildRules": [
{
"level": [0, 1, 2],
"value": {
"filter": "code!=0",
"attrFields": ["name", "color"],
"merge": ["code=1"]
}
}
]
}Examples
Build a pyramid with default settings
Pass an empty string as config to use all default values.
SELECT ST_BuildPyramid('roads', 'geom', 'id', '');Expected output:
st_buildpyramid
-----------------
t