Calculates the percentiles of the specified bands of a raster object and stores the results back in the raster.
Syntax
-- Calculate percentiles for all bands
raster ST_BuildPercentiles(raster raster_obj,
cstring sampleOption default '{}')
-- Calculate percentiles for specific bands, with parallelism control
raster ST_BuildPercentiles(raster raster_obj,
cstring bands,
cstring sampleOption default '{}',
cstring parallelOption default '{}')Use the second overload when you need to target specific bands or control the degree of parallelism.
Parameters
| Parameter | Type | Description |
|---|---|---|
raster_obj | raster | The raster object to process. |
bands | cstring | The band IDs to include. Example: '0,1-3,6,8'. Band IDs start from 0. Pass '' to include all bands. |
sampleOption | cstring | A JSON string of sampling options. See sampleOption parameters. |
parallelOption | cstring | A JSON string of parallel execution options. See parallelOption parameters. |
sampleOption parameters
Settingapproxtotrueenables approximate sampling, which is faster but may produce inaccurate results. Use exact mode (approx: false) when precision matters.
| Parameter | Type | Default | Description |
|---|---|---|---|
approx | boolean | false | Specifies whether to use approximate sampling. When true, results may be inaccurate. |
factor | integer | 4 | The sampling factor — the number of pixels per sampling unit. Valid values: 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
All examples use UPDATE to write the computed percentiles back to the raster object.
Default settings — all bands, exact sampling:
UPDATE raster_table SET raster_obj = ST_BuildPercentiles(raster_obj) WHERE id = 1;Specific bands with exact sampling:
UPDATE raster_table SET raster_obj = ST_BuildPercentiles(rast, '0-2', '{"approx":false}') WHERE id = 1;All bands with exact sampling (explicit):
UPDATE raster_table SET raster_obj = ST_BuildPercentiles(rast, '{"approx":false}') WHERE id = 1;Specific bands with approximate sampling and parallelism:
UPDATE raster_table SET raster_obj = ST_BuildPercentiles(raster_obj, '0-2', '{"approx":true, "factor":5}', '{"parallel":4}') WHERE id = 1;