ST_AsDatasetFile Function Reference for Raster Export - PolarDB

Exports a spatial subset of a raster object as a BYTEA file in the specified format.

Syntax

setof record ST_AsDatasetFile(raster raster_obj,
                              box extent,
                              integer pyramidLevel default 0,
                              cstring bands default '',
                              cstring format default 'GTiff',
                              cstring create_option default '{}',
                              cstring process_option default '{}',
                              out ext cstring,
                              out data bytea);

Parameters

Parameter	Type	Default	Description
`raster_obj`	raster	—	The raster object to export.
`extent`	box	—	The spatial extent to extract. By default, coordinates are interpreted as geographic coordinate system (GCS) values. To use pixel coordinates instead, set `rast_coord` to `true` in `process_option`.
`pyramidLevel`	integer	`0`	The pyramid level to extract data from. Valid values start from `0`.
`bands`	cstring	`''`	The band IDs to extract. Valid band IDs start from `0`. Accepts a range (`'0-2'`) or a comma-separated list (`'1,2,3'`). An empty string extracts all bands.
`format`	cstring	`'GTiff'`	The output file format. For supported formats, see ST_RasterDrivers.
`create_option`	cstring	`'{}'`	A JSON string of dataset creation options. Valid values come from the `create_options` field in ST_RasterDrivers.
`process_option`	cstring	`'{}'`	A JSON string of processing options. Set `rast_coord` to `true` to interpret the `extent` bounding box as pixel coordinates, where x is the column number and y is the row number (both starting from `0`).
`ext` (out)	cstring	—	The file extension of the output. Supported values: `TIF`, `XML`.
`data` (out)	bytea	—	The file content as BYTEA data.

Usage notes

The format must be supported by a Ganos driver with can_asfile set to true. To check supported formats, query ST_RasterDrivers.
The function returns up to 100 MB of data by default. To change this limit, set the ganos.raster.clip_max_buffer_size parameter.

Examples

All examples query raster_table and filter by id = 1. Each call returns one or more records containing the file extension (ext) and file content (data).

Extract a geographic extent (default settings)

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box)
FROM raster_table
WHERE id = 1;

Extract from a specific pyramid level

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box,
                        1)
FROM raster_table
WHERE id = 1;

Extract specific bands

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box,
                        1,
                        '0-2')
FROM raster_table
WHERE id = 1;

Export as GIF

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box,
                        1,
                        '0-2',
                        'GIF')
FROM raster_table
WHERE id = 1;

Export as GTiff with compression

SELECT ST_AsDatasetFile(raster_obj,
                        '(-180,-90), (0,0)'::Box,
                        1,
                        '0-2',
                        'GTiff',
                        '{"blockxsize":256, "blockysize":256, "compress": "DEFLATE"}')
FROM raster_table
WHERE id = 1;

Extract using pixel coordinates as the bounding box

SELECT ST_AsDatasetFile(raster_obj,
                        '(0,0), (100,100)'::Box,
                        1,
                        '0-2',
                        'GTiff',
                        '{}',
                        '{"rast_coord":"true"}')
FROM raster_table
WHERE id = 1;