ST_CreateRast-AnalyticDB(AnalyticDB)-阿里云帮助中心

Creates a raster object from an Object Storage Service (OSS) object, a MinIO object, a Hadoop Distributed File System (HDFS) file, or a one-dimensional array.

Syntax

raster ST_CreateRast(cstring url);
raster ST_CreateRast(cstring url, cstring storageOption);
raster ST_CreateRast(anyarray data, integer width, cstring storageOption, geometry extent);

Parameters

Parameter	Description
`url`	The path of the source object. For supported URL formats and protocols, see Object storage paths.
`storageOption`	A JSON string that defines the chunk layout for storing the raster pyramid. For supported fields, see storageOption fields.
`createOption`	A JSON string that controls band statistics calculation during import. For supported fields, see createOption fields.
`data`	Raster data as a one-dimensional array. The number of elements must equal the number of columns multiplied by the number of rows.
`width`	The number of columns in the raster data.
`extent`	(Optional) The spatial extent of the raster, represented as a geometry.

storageOption fields

Field	Type	Format	Default	Description
`chunkdim`	string	`(w,h,b)`	Same as the source object	The chunk dimensions for storing raster data.
`interleaving`	string	—	`bsq`	The band interleaving method. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ), `auto` (selected automatically).
`chunk_table`	string	—	None	The name of the chunk table. Required when generating a raster object from an array.

Note Change chunkdim or interleaving only when necessary:

Change interleaving to bip when users need multiband RGB combination rendering and the current value is bsq.
Change chunkdim when the source image has chunks of 1×n pixels but you need 256×256 chunks.

createOption fields

Field	Type	Default	Description
`compute_stats`	boolean	`false`	Specifies whether to automatically calculate band statistics during import.
`approx`	boolean	`false`	Specifies whether to use sampling to calculate statistics. If set to `true`, results may be less accurate.
`factor`	integer	`4`	The sampling factor. A value of `n` means each sampling unit covers `n` pixels. Takes effect only when `approx` is `true`.
`exclusive_nodata`	boolean	`true`	Specifies whether to exclude nodata values from statistics calculations.

Usage notes

URL format

The URL format for OSS objects is oss://access_id:secret_key@Endpoint/path_to/file. The endpoint is optional — if omitted, the system resolves it automatically, but the path must start with a forward slash (/).

The endpoint is the domain name used to access the OSS bucket. For best import performance, deploy your AnalyticDB for PostgreSQL instance in the same region as the OSS bucket. For more information, see s.

Supported protocols

Protocol	URL format	Example
OSS	`OSS://<ak>:<ak_secret>@<endpoint>/<bucket>/<path>`	`OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif`
MinIO	`MIO://<ak>:<ak_secret>@<host>:<port>/<bucket>/<path>`	`MIO://<ak>:<ak_secret>@10.0.0.1:443/mybucket/data/image.tif`
HDFS	`HDFS://<user_name>@<host>:<port>/<path>`	`HDFS://<user_name>@10.0.0.1:8020/path/image.tif`

Examples

Create a raster object from an OSS object

Specify the AccessKey ID, AccessKey secret, and endpoint in the URL.

SELECT ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif');

Create a raster object from a MinIO object

Specify the host and port in the URL.

SELECT ST_CreateRast('MIO://<ak>:<ak_secret>@10.0.0.1:443/mybucket/data/image.tif');

Create a raster object from an HDFS file

Specify the username in the URL.

SELECT ST_CreateRast('HDFS://<user_name>@10.0.0.1:8020/path/image.tif');

Set chunk dimensions and band interleaving

Use storageOption to override the default chunk layout.

SELECT ST_CreateRast(
  'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif',
  '{"chunkdim":"(256,256,3)","interleaving":"auto"}'
);

Calculate band statistics during import

Pass createOption with compute_stats set to true.

SELECT ST_CreateRast(
  'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif',
  '{"chunkdim":"(256,256,3)","interleaving":"auto"}',
  '{"compute_stats":true}'
);

Create a raster object from a NetCDF image with subsets

Append the subset name after a colon (:) at the end of the URL.

SELECT ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc');

Create a raster object from an HDF5 image with subsets

Append the dataset path after :// at the end of the URL.

SELECT ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.hdf5://ds/hcc');

Create a raster object from an array

Pass a one-dimensional array, the number of columns, a storageOption with chunk_table specified, and an optional geometry extent.

SELECT ST_FixedRid(
  ST_CreateRast(
    ARRAY[10, 11, 8, 12],
    2,
    '{"chunktable":"rbt"}',
    ST_GeomFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))', 4326)
  )
);

Aggregate records into a raster object

Use array_agg to collect values from a table before passing them to ST_CreateRast.

SELECT ST_FixedRid(
  ST_CreateRast(
    (SELECT array_agg(value) FROM point_table),
    300,
    '{"chunktable":"rbt"}'
  )
);