All Products
Search

This Product

    PolarDB:ST_BuildPyramid

    Document Center

    PolarDB:ST_BuildPyramid

    Last Updated:Mar 28, 2026

    Builds a multi-resolution pyramid for a raster object to improve display and query performance.

    Syntax

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

    Usage notes

    • GPU-accelerated computing is supported. In environments where GPUs are available, Ganos enables it automatically.

    • When you set parallel in buildOption, transactions are not supported. If pyramid creation fails, call ST_deletePyramid to clean up before retrying.

    Parameters

    ParameterDefaultDescription
    source—The raster object to build the pyramid for.
    pyramidLevel-1The number of pyramid levels to build. -1 builds the maximum number of levels.
    algorithm'Near'The resampling algorithm. See Algorithm values.
    chunkTableName''The chunk table to store pyramid data. Takes effect only when the raster object is stored in an Object Storage Service (OSS) bucket.
    storageOption'{}'A JSON string specifying chunk storage parameters for the pyramid. Takes effect only when the raster object is stored in an OSS bucket. See storageOption parameters.
    buildOption'{}'A JSON string specifying pyramid build parameters. Supports the parallel key, which sets the degree of parallelism as an integer from 1 to 64. If omitted, the value of the ganos.parallel.degree GUC parameter is used.

    Algorithm values

    • Near (default)

    • Average

    • Bilinear

    • Cubic

    storageOption parameters

    ParameterTypeDefaultDescription
    chunkdimstringDerived from the source imageThe chunk dimensions in (w, h, b) format.
    interleavingstringbsqThe band interleaving method: bip (band interleaved by pixel), bil (band interleaved by line), bsq (band sequential), or auto (determined automatically).
    compressionstringLZ4The compression format: none, jpeg, zlib, png, lzo, LZ4, zstd, snappy, or jp2k.
    qualityinteger75The compression quality, from 1 to 99. Applies only to JPEG and JPEG 2000 (jp2k).

    Examples

    Build a pyramid with default settings:

    UPDATE raster_table SET raster_obj = ST_BuildPyramid(raster_obj) WHERE id = 1;

    Build a pyramid and store it in a named chunk table:

    UPDATE raster_table SET raster_obj = ST_BuildPyramid(raster_obj, 'chunk_table') WHERE id = 2;

    Build a pyramid using JPEG 2000 compression, with all bands in a single chunk:

    -- All four bands fit within one (256x256) 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;

    Build a pyramid in parallel using four threads:

    -- Parallel execution does not support transactions.
-- If this fails, call ST_deletePyramid before retrying.
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;

    What's next