All Products
Search

This Product

    PolarDB:ST_MapAlgebra

    Document Center

    PolarDB:ST_MapAlgebra

    Last Updated:Mar 28, 2026

    ST_MapAlgebra merges multiple raster objects into a single raster object by applying algebraic expressions written in Algebra Computing Language.

    Syntax

    raster ST_MapAlgebra(raster[] rasters,
        cstring algebraExpr  default NULL,
        cstring storageoption default '')

    Parameters

    ParameterDescription
    rastersThe input raster objects to transform.
    algebraExprA JSON string that defines the algebraic expressions to apply. See algebraExpr parameter.
    storageOptionA JSON string that controls how the output raster is stored. See storageOption parameter.
    ST_MapAlgebra only requires that the input rasters share the same unit of measurement for length and width. It does not check spatial reference systems or resolutions. If your rasters use different units, use ST_Transform, ST_Resize, and ST_Clip to align them first.

    algebraExpr parameter

    The algebraExpr parameter takes a JSON array. Each object in the array defines one output band using the following fields.

    Fields

    FieldTypeDefaultDescription
    algebraExprString—The algebraic expression for this band.
    nodataBooleanfalseControls how nodata pixels are handled. true: nodata pixels are treated as valid and are not transformed. false: nodata pixels are treated as invalid and are transformed.
    nodataValuefloat80The nodata value written to the output raster.

    Expression keywords

    Use the following keywords in algebraic expressions to reference pixel values:

    1. [r, b] — The pixel value at raster index r and band index b, both zero-based (0 to n−1).

    2. x — The zero-based column index of the current pixel.

    3. y — The zero-based row index of the current pixel.

    Supported operations

    TypeOperators and functionsNotes
    Arithmetic+, -, *, /, % (remainder), ** (power)—
    Bitwise<<, >>, &, |, ^—
    Logical<, >, ==, !=, <=, >=, &&, ||, !—
    Math functionsabs, sqrt, exp, log, ln, sin, cos, tan, sinh, cosh, tanh, arcsin, arccos, arctan, ceil, floor, roundOnly one math function per expression.
    Statistical functionsmin, max, sum, mean, majority, minority, std, median, range, varietyRequires two or more arguments.

    algebraExpr examples

    Example 1 — Single-band output using an arithmetic expression

    Produces a one-band raster using raster[0]band[0] + raster[1]band[0] * raster[1]band[1]:

    [
    {
        "expr": "([0,0] + [1,0] * [1,1]) ",
        "nodata": true,
        "nodataValue": 999
    }
]

    Example 2 — Single-band output using a statistical function

    Computes the standard deviation across three bands of the first raster:

    [
    {
        "expr": "(std([0,0],[0,1],[0,2]))",
        "nodata": true,
        "nodataValue": 999
    }
]

    Example 3 — Multi-band output with a unique expression per band

    Produces a three-band raster, applying min, max, and mean across three bands:

    [
    {
        "expr": "(min([0,0],[0,1],[0,2]))",
        "nodata": true,
        "nodataValue": 999
    },
    {
        "expr": "(max([0,0],[0,1],[0,2]))",
        "nodata": true,
        "nodataValue": 999
    },
    {
        "expr": "(mean([0,0],[0,1],[0,2]))",
        "nodata": true,
        "nodataValue": 999
    }
]

    storageOption parameter

    FieldTypeDefaultDescription
    chunkingBooleanSame as input rasterWhether to store the output raster as chunks.
    chunkdimStringSame as input rasterThe chunk dimensions. Takes effect only when chunking is true.
    chunktableString'' (empty string)The name of the chunk table. By default, a temporary table with a random name is created and is only valid for the current session. Specify a name to store the output permanently.
    compressionStringSame as input rasterThe compression format. Valid values: None, JPEG, Zlib, PNG, LZO, LZ4.
    qualityIntegerSame as input rasterThe image quality. Takes effect only in JPEG format.
    interleavingStringSame as input rasterThe interleaving type. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ).
    endianStringSame as input rasterThe byte order. Valid values: NDR (little endian), XDR (big endian).

    Examples

    The following example creates a permanent chunk table, then inserts the result of ST_MapAlgebra into it. Both rasters are collected into an array, and a single arithmetic expression combines band 0 from the first raster with band 0 and band 1 from the second raster.

    -- Create a permanent chunk table.
CREATE TABLE rast_mapalgebra_result(id integer, rast raster);

-- Insert data into a chunk table.
WITH foo AS (
  SELECT 1 AS rid, rast AS rast from t1 WHERE id = 1
UNION ALL
  SELECT 2 AS rid, rast AS rast from t2 WHERE id = 2
)
INSERT INTO rast_mapalgebra_result
SELECT 1, ST_MapAlgebra(
    ARRAY(SELECT rast FROM foo ORDER BY rid),
    '[{"expr":"([0,0] + 0.5 * [1,0] - ([1,1])","nodata": true, "nodataValue":999}]',
    '{"chunktable":"algebra_rbt"}'
);