Use ST_ComputeStatistics to collect statistics for a raster - PolarDB

Computes statistics for a raster object, including histograms and percentiles, and returns the updated raster.

Syntax

raster ST_ComputeStatistics(raster raster_obj,
                            cstring sampleOption default '{}')

raster ST_ComputeStatistics(raster raster_obj,
                            cstring bands,
                            cstring sampleOption default '{}',
                            cstring parallelOption default '{}')

Parameters

Parameter	Description
`raster_obj`	The raster object to compute statistics for.
`bands`	The band IDs to process, specified as a comma-separated list or range. Example: `'0,1-3,6,8'`. Band IDs start from `0`. To process all bands, pass an empty string `''`.
`sampleOption`	A JSON string with sampling options. See sampleOption parameters.
`parallelOption`	A JSON string with parallel execution options. See parallelOption parameters.

sampleOption parameters

Parameter	Type	Default	Description
`approx`	boolean	`false`	Specifies whether to use approximate sampling. When `true`, the function samples a subset of pixels rather than the full raster—faster, but the returned statistics may be less accurate.
`factor`	integer	`4`	The sampling factor: the number of pixels per sampling unit. Any positive integer. Takes effect only when `approx` is `true`.
`exclusive_nodata`	boolean	`true`	Specifies whether to include NoData values.

parallelOption parameters

Parameter	Type	Default	Description
`parallel`	integer	`ganos.parallel.degree`	The degree of parallelism. Valid values: 1 to 64.

Examples

Use default settings

Compute statistics for all bands using exact sampling:

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

Specify bands and disable approximate sampling

Compute exact statistics for bands 0 through 2:

UPDATE raster_table SET raster_obj = ST_ComputeStatistics(rast, '0-2', '{"approx":false}') WHERE id = 1;

Disable approximate sampling for all bands

UPDATE raster_table SET raster_obj = ST_ComputeStatistics(rast, '{"approx":false}') WHERE id = 1;

Use approximate sampling with parallel execution

Compute statistics for bands 0–2 using a sampling factor of 5 and 4 parallel workers:

UPDATE raster_table SET raster_obj = ST_ComputeStatistics(raster_obj, '0-2', '{"approx":true, "factor":5}', '{"parallel":4}') WHERE id = 1;

When approx is true, the function trades accuracy for speed. Use exact sampling (approx: false) for production workloads where precise histograms and percentiles are required.