All Products
Search

This Product

    PolarDB:ST_MapAlgebra

    Document Center

    PolarDB:ST_MapAlgebra

    Last Updated:Mar 27, 2026

    Applies algebraic expressions written in Algebra Computing Language to one or more raster objects and returns the result as a new raster object.

    Syntax

    raster ST_MapAlgebra(raster[] rasters,
        cstring algebraExpr DEFAULT NULL,
        cstring storageOption DEFAULT '')

    Parameters

    ParameterTypeDefaultDescription
    rastersraster[]—The input raster objects to transform.
    algebraExprcstringNULLA JSON string that defines the algebraic expressions to apply. See algebraExpr parameter.
    storageOptioncstring''A JSON string that controls how to store the output raster object. See storageOption parameter.

    Usage notes

    ST_MapAlgebra only checks that all input raster objects use the same unit of measurement for length and width. It does not check spatial reference systems or resolutions. If the input rasters use different units, convert them to the same unit first. The following functions can help:

    algebraExpr parameter

    Pass a JSON array where each element defines the expression for one output band. The following table describes the fields in each element.

    FieldTypeDefaultDescription
    exprstring—The algebraic expression to evaluate.
    nodataBooleanfalseControls how pixels with nodata values are handled. true: pixels with nodata values are skipped and not transformed. The output value for those pixels is set to nodataValue. false: pixels with nodata values are transformed like any other pixel.
    nodataValuefloat80The nodata value assigned to output pixels that are skipped when nodata is true.

    Expression syntax

    An expression can reference any pixel in the input rasters using the following keywords:

    KeywordDescription
    [r, b]The pixel value at raster index r and band index b. Both indices are 0-based (0 to n−1).
    xThe sequence number of the column where the specified pixel resides.
    yThe sequence number of the row where the specified pixel resides.

    Supported operations

    TypeOperators and functions
    Arithmetic+, -, *, /, % (remainder), ** (power)
    Bitwise<<, >>, &, |, ^
    Logical<, >, ==, !=, <=, >=, &&, ||, !
    Math functionsabs, sqrt, exp, log, ln, sin, cos, tan, sinh, cosh, tanh, arcsin, arccos, arctan, ceil, floor, round — specify only one math function per expression.
    Statistical functionsmin, max, sum, mean, std (standard deviation), median, range (max minus min), majority (most frequent value), minority (least frequent value), variety (count of unique values) — each statistical function requires two or more band arguments.

    algebraExpr examples

    Example 1: Single-band output from multiple input rasters

    The expression computes rasters[0] band 0 + rasters[1] band 0 × rasters[1] band 1 and writes the result to one output band.

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

    Example 2: Standard deviation across bands of one raster

    The expression computes the standard deviation of three bands from rasters[0].

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

    Example 3: Multi-band output with per-band expressions

    Each element in the array defines the expression for one output band. This example produces a three-band raster using min, max, and mean across three bands of rasters[0].

    [
    {
        "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 inputWhether to store the output raster as chunks.
    chunkdimstringSame as inputThe chunk dimensions. Takes effect only when chunking is true.
    chunktablestring''The name of the chunk table. By default, a temporary chunk table with a randomly generated name is created and is only valid for the current session. Specify a name to create a permanent chunk table.
    compressionstringSame as inputThe compression format. Valid values: None, JPEG, Zlib, PNG, LZO, LZ4.
    qualityintegerSame as inputThe image quality. Takes effect only when compression is JPEG.
    interleavingstringSame as inputThe interleaving type. Valid values: bip (band interleaved by pixel, BIP), bil (band interleaved by line, BIL), bsq (band sequential, BSQ).
    endianstringSame as inputThe byte order. NDR: little endian. XDR: big endian.

    Examples

    The following example reads raster data from two source tables, applies a band algebra expression, and saves the result to a permanent chunk table.

    -- Create a table to store the result.
CREATE TABLE rast_mapalgebra_result(id integer, rast raster);

-- Apply the expression and insert the result.
-- [0,0] = rasters[0] band 0 (rast from t1 where id = 1)
-- [1,0] = rasters[1] band 0 (rast from t2 where id = 2)
-- [1,1] = rasters[1] band 1 (rast from t2 where id = 2)
WITH foo AS (
  SELECT 1 AS rid, rast FROM t1 WHERE id = 1
  UNION ALL
  SELECT 2 AS rid, 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"}'
);