All Products
Search

This Product

    PolarDB:ST_SubRaster

    Document Center

    PolarDB:ST_SubRaster

    Last Updated:Mar 28, 2026

    ST_SubRaster extracts a subset of a raster object — specific bands, a pyramid level, or both — and returns it as a new raster object. Use it to export selected bands, change pixel type, or build derived rasters for downstream processing.

    Syntax

    raster ST_SubRaster(raster raster_obj,
                    integer pyramidLevel DEFAULT 0,
                    cstring bands DEFAULT '',
                    cstring storageOption DEFAULT '',
                    cstring options DEFAULT '{}')

    Parameters

    ParameterTypeDefaultDescription
    raster_objraster—The source raster object.
    pyramidLevelinteger0The pyramid level to extract.
    bandscstring''The bands to extract. An empty string extracts all bands. See Band selection for the accepted formats.
    storageOptioncstring''A JSON string that controls how the new raster object is stored. See storageOption keys.
    optionscstring'{}'A JSON string that controls how the new raster object is generated. See options keys.

    Band selection

    The bands parameter accepts two formats. Both use 0-based indexing.

    FormatExampleDescription
    Range'0-2'Extracts bands 0, 1, and 2 (inclusive).
    List'1,2,3'Extracts the specified bands in order.

    storageOption keys

    All keys are optional. Omitting a key preserves the corresponding setting from the source raster object.

    KeyTypeDefaultDescription
    chunkingBooleanSame as sourceSpecifies whether to store the new raster object as chunks.
    chunkdimstringSame as sourceChunk dimensions. Valid only when chunking is true.
    chunktablestring''Name of the chunk table. An empty string or null creates a temporary chunk table that is valid only for the current session. Specify a name to create a permanent chunk table.
    compressionstringSame as sourceCompression format. Valid values: NONE, JPEG, ZLIB, PNG, LZO, LZ4.
    qualityintegerSame as sourceJPEG image quality after compression. Valid values: 1–99. Valid only when compression is JPEG.
    interleavingstringSame as sourceBand interleaving format. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ).
    endianstringSame as sourceByte order. Valid values: NDR (little-endian), XDR (big-endian).
    celltypestringSame as sourcePixel type of the new raster object. See Pixel types for valid values.

    options keys

    KeyTypeDefaultDescription
    parallelintegerganos.parallel.degreeDegree of parallelism. Valid values: 1–64.
    stretchstringnonePixel value stretch method when converting pixel types. Valid values: none, stats, data_type. See Pixel value stretching.

    Pixel value stretching

    The stretch option controls what happens to pixel values that fall outside the range supported by the target pixel type.

    ValueBehaviorPrerequisite
    noneClamps out-of-range values to the minimum or maximum of the target pixel type.None.
    statsScales values based on the statistics of the source raster.Run ST_SummaryStats on the source raster before calling ST_SubRaster.
    data_typeScales values across the full representable range of the target pixel type.None.

    Pixel types

    The following values are valid for celltype:

    ValueDescription
    1bb1-bit Boolean
    2bui2-bit unsigned integer
    4bui4-bit unsigned integer
    8bsi8-bit signed integer
    8bui8-bit unsigned integer
    16bsi16-bit signed integer
    16bui16-bit unsigned integer
    32bsi32-bit signed integer
    32bui32-bit unsigned integer
    64bsi64-bit signed integer
    64bui64-bit unsigned integer
    32bf32-bit floating-point number
    64bf64-bit floating-point number

    Examples

    Extract specific bands into a new raster object

    The following example extracts bands 0–2 from pyramid level 1 and stores the result in a permanent chunk table named chunk_table.

    SELECT ST_SubRaster(rast, 1, '0-2', '{"chunktable":"chunk_table", "chunking":true}')
FROM raster_sub
WHERE id = 1;

    Convert pixel type and stretch values in parallel

    The following example converts bands 0–2 to 8BUI pixel type, scales values to the full 8BUI range, and runs the operation across 4 parallel workers.

    SELECT ST_SubRaster(rast, 1, '0-2',
    '{"chunktable":"chunk_table", "chunking":true, "celltype":"8BUI"}',
    '{"stretch":"data_type", "parallel":4}')
FROM raster_sub
WHERE id = 1;

    What's next