This topic describes the ST_BuildPyramid function, which creates a vector pyramid for a spatial geometry data table to accelerate the display of data.


boolean ST_BuildPyramid(cstring table, cstring geom, cstring fid, cstring config)


Parameter Description
table The name of the spatial geometry data table.
geom The name of the geometry field.
fid The name of the element ID field.
config The fields that are used to create a pyramid. These fields are specified as a JSON string.

The following table describes the fields in the config parameter.

Field Type Default value Description
name string Same as the table name The name of the pyramid.
parallel int 0 The maximum number of tasks that can run in parallel to create the pyramid. You must also specify the max_prepared_transactions parameter. If you set the parallel parameter to 0, the maximum number of parallel tasks is not limited.
tileSize int 1024 The tile size of the pyramid. Valid values must be greater than 0 and less than 4096.
tileExtend int 8 The tile extension size of the pyramid. Valid values must be greater than 0.
userExtent array[double] null The geographic bound that you define. The value of this parameter is a JSON string. This JSON string consists of four fields: minx, miny, maxx, and maxy. If you set this parameter to [], the value is null.
splitSize int 10000 The maximum number of elements into which an index node can be split. A larger value of this parameter indicates a sparser pyramid.
maxLevel int 16 The maximum number of layers in the pyramid. Valid values: 0 to 20.
sourceSRS int -1 The coordinate system of the source data in the spatial geometry data table. If you do not specify this parameter, the system reads the spatial reference identifiers (SRIDs) in the metadata.
destSRS int 3857 The EPSG code of the title coordinate system. Only EPSG 3857 and EPSG 4326 are supported.
buildRules array[object] null The rule based on which you want to create the pyramid. You can specify multiple rules. Each rule consists of two parts: level and value.
level array[int] None The pyramid layers to which the specified rule is applied.
value object None The value of the specified rule.
filter string None The expression that is used to filter data in PostgreSQL.
attrFields array[string] None The name of the attribute field when the MVT format is used.
merge array[string] None The filter conditions that are used to add data records to a group.

The following example shows how to set the config parameter:

   "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"],    


--Create a pyramid for a spatial geometric data table named roads. 
select ST_BuildPyramid('roads', 'geom', 'id', '');