This topic describes the ST_BuildPyramid function, which is used to create a pyramid for a raster object.

Syntax

raster ST_BuildPyramid(raster source,  
                       integer pyramidLevel default -1,  
                       ResampleAlgorithm algorithm default 'Near', 
                       cstring chunkTableName default '', 
                       cstring storageOption default '{}',
                       cstring buildOption default '{}');

Parameters

Parameter Description
source The name of the raster object.
chunkTableName The name of the chunk table that is stored in the pyramid. This parameter takes effect only when the raster object is stored in an Object Storage Service (OSS) bucket.
pyramidLevel The number of levels in the pyramid. The value -1 specifies that the largest number of levels are created in the pyramid.
algorithm The resampling algorithm that is used to create the pyramid. Valid values:
  • Near
  • Average
  • Bilinear
  • Cubic
storageOption The JSON string that is used to specify the storage-related parameters. These parameters are used to describe the chunk storage information of the pyramid. This JSON string takes effect only when the raster object is stored in an OSS bucket.
buildOption The JSON string that is used to specify the pyramid building-related parameters. PolarDB supports the parallel parameter. This parameter specifies the degree of parallelism. The data type of this parameter is INTEGER. The value of this parameter ranges from 1 to 64. If you do not specify the parallel parameter, the value of the GUC parameter ganos.parallel.degree is used as the default degree of parallelism. For more information, see ganos.parallel.degree.
Note If you run threads in parallel to create the pyramid, transactions are not supported. If the pyramid cannot be created or you need to roll transactions back, you can invoke the ST_deletePyramid function to delete the pyramid. For more information, see ST_deletePyramid.

The following table describes the parameters in storageOption.

Parameter Type Description
chunkdim string The dimensions that are used to chunk the data of the raster object. The value of this parameter follows the (w, h, b) format. By default, the size per chunk is obtained from the original image data.
interleaving string The method that is used to interleave the data of the raster object.
  • bip: band interleaved by pixel (BIP)
  • bil: band interleaved by line (BIL)
  • bsq: band sequential (BSQ) (This is the default value.)
  • auto: an interleaving method that is specified by this function
compression string The format into which you want to compress the data of the raster object. Valid values:
  • none
  • jpeg
  • zlib
  • png
  • lzo
  • LZ4 (This is the default value.)
  • zstd
  • snappy
  • jp2k
quality integer The quality of compression. This parameter takes effect only when you use the JPEG or JPEG 2000 compression format. Default value: 75.

Description

This function supports GPU-accelerated computing. By default, in an active environment with GPUs, Ganos automatically enables GPU-accelerated computing.

Examples

Update raster_table set raster_obj = ST_BuildPyramid(raster_obj) where id = 1;

Update raster_table set raster_obj = ST_BuildPyramid(raster_obj, 'chunk_table') where id = 2;

-- Use JPEG 2000 to compress the data of the raster object.
-- Make sure that all bands are within one chunk.
Update raster_table set raster_obj = ST_BuildPyramid(
    raster_obj, 
    -1, 
    'Near', 
    'chunk_table', 
    '{"compression":"jp2k", "quality": 75, "chunkdim":"(256,256,4)","interleaving":"auto"}') 
where id = 3;

-- Create the pyramid by using parallel operations.
Update raster_table set raster_obj = ST_BuildPyramid(
    raster_obj, 
    -1, 
    'Near', 
    'chunk_table', 
    '{"compression":"jp2k", "quality": 75, "chunkdim":"(256,256,4)","interleaving":"auto"}', 
    '{"parallel":4}') 
where id = 3;