Returns band-level statistics for a raster object. Use Syntax 1 to retrieve statistics for a single band as JSON. Use Syntax 2 to compute statistics within a geometry-defined region, with optional pixel value range filtering.
Syntax
Syntax 1 — returns band statistics as JSON:
TEXT ST_Statistics(raster raster_obj, integer band);Syntax 2 — returns per-range statistics within a geometry region:
SETOF RECORD ST_Statistics(
raster raster_object,
geometry geom,
integer band default 0,
cstring statics_range default '',
boolean rast_coord default true,
out cstring name,
out integer band,
out float8 min,
out float8 max,
out float8 mean,
out float8 sum,
out float8 count,
out float8 std,
out float8 median,
out float8 mode
);Description
Syntax 1: Returns statistics for the specified band of a raster object in JSON format. Returns
nullif no statistics exist for the band.Syntax 2: Computes statistics for pixels within the region defined by a geometry object. If the geometry has an M value, the M value is used as the pixel weight. When
statics_rangeis set, the function returns one row per range interval plus afullrow covering all pixels.
Parameters
Input parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
raster_obj / raster_object | raster | — | The raster object to compute statistics on. |
band | integer | 0 | The band index, starting from 0. |
geom | geometry | — | The geometry object that defines the region of interest. If the geometry has an M value, the M value is used as the pixel weight. |
statics_range | cstring | '' | The pixel value range filter. Specify one or more boundary values separated by commas (,). The default value (] indicates an empty range. See statics_range syntax below. |
rast_coord | boolean | true | Specifies whether the pixel coordinate is used. |
statics_range syntax
statics_range accepts a sequence of numeric boundary values and bracket symbols to define one or more consecutive intervals:
| Symbol | Meaning |
|---|---|
( | Greater than (exclusive lower bound) |
) | Less than (exclusive upper bound) |
[ | Greater than or equal to (inclusive lower bound) |
] | Less than or equal to (inclusive upper bound) |
Examples:
[300,400,500)— open or closed range at the start and end.(300,400,500]— open or closed range at the start and end.(0, 10, 20,100,1000]— defines four intervals:(0-10],(10-20],(20-100],(100-1000].
Output fields (Syntax 2 only)
| Field | Type | Description |
|---|---|---|
name | cstring | The range label. full indicates statistics across all pixels; otherwise, the value shows the interval, for example (300, 400]. |
band | integer | The band index. |
min | float8 | The minimum pixel value in the range. |
max | float8 | The maximum pixel value in the range. |
mean | float8 | The mean pixel value in the range. |
sum | float8 | The sum of pixel values in the range. |
count | float8 | The number of pixels in the range. |
std | float8 | The standard deviation of pixel values in the range. |
median | float8 | The median pixel value in the range. |
mode | float8 | The most frequent pixel value in the range. |
Empty rows in the result indicate that no pixels fall within that interval.
Examples
Band statistics as JSON (Syntax 1)
Returns statistics for band 0 of the raster with id=1:
SELECT ST_Statistics(raster_obj, 0) FROM raster_table WHERE id=1;Result:
'{ "min" : 0.00, "max" : 255.00,"mean" : 125.00,"std" : 23.123,"approx" : false}'Statistics within a MultiPoint geometry, no range filter (Syntax 2)
Computes statistics for band 0 within the region defined by a MultiPoint geometry. The M values (10, 50, 100) act as pixel weights:
SELECT (ST_Statistics(raster_obj,
'MultiPoint((0 0 10), (100 100 50), (199 199 100))'::geometry,
0)).*
FROM raster_table WHERE id=1;Result:
name | band | min | max | mean | sum | count | std | median | mode
------+------+-----+-----+----------+-------+-------+------------------+--------+------
full | 2 | 47 | 196 | 140.3125 | 22450 | 160 | 71.8955133770529 | 47 | 196Statistics within a MultiPoint geometry, with range filter (Syntax 2)
Filters statistics to specific pixel value ranges. The range string (0, 10, 20,100,1000] defines four intervals. The function returns one row per interval plus a full row. Empty rows indicate no pixels fall in that interval:
SELECT (ST_Statistics(raster_obj,
'MultiPoint((0 0 10), (100 100 50), (199 199 100))'::geometry,
0,
'(0, 10, 20,100,1000]')).*
FROM raster_table
WHERE id=1;Result:
name | band | min | max | mean | sum | count | std | median | mode
------------+------+-----+-----+------+-------+-------+------------------+--------+------
full | 0 | 1 | 202 | 82 | 246 | 3 | 86.5678924313166 | 202 | 1
(0-10] | 0 | 1 | 1 | 1 | 1 | 1 | 0 | 1 | 1
(10-20] | 0 | | | | | | | |
(20-100] | 0 | 43 | 43 | 43 | 43 | 1 | 0 | 43 | 43
(100-1000] | 0 | 202 | 202 | 202 | 202 | 1 | 0 | 202 | 202Statistics within a Polygon, with range filter (Syntax 2)
Computes ranged statistics for band 1 within a polygon region. Results include id to correlate with the source row:
SELECT id, (ST_Statistics(rast,
ST_geomfromtext('POLYGON((50 50,55 50,55 55,50 55,50 50))'),
1,
'(0, 10, 20,100,1000]')).*
FROM raster_table WHERE id = 1;Result:
id | name | band | min | max | mean | sum | count | std | median | mode
----+------------+------+-----+-----+------------------+-------+-------+------------------+--------+------
3 | full | 0 | 48 | 103 | 78.1020408163265 | 3827 | 49 | 21.5815916437107 | 97 | 97
3 | (0-10] | 0 | | | | | | | |
3 | (10-20] | 0 | | | | | | | |
3 | (20-100] | 0 | 48 | 97 | 76.4782608695652 | 3518 | 46 | 21.2855729161028 | 97 | 97
3 | (100-1000] | 0 | 103 | 103 | 103 | 309 | 3 | 0 | 103 | 103
(5 rows)