ST_CreateRast Overview: Raster Objects from OSS & HDFS - PolarDB

ST_CreateRast creates a raster object from a file stored in Alibaba Cloud Object Storage Service (OSS), a self-managed Multi-Cloud Object Storage (MinIO) bucket, or a Hadoop Distributed File System (HDFS) file. It can also generate a raster object from 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);

The three overloads fall into two groups:

Create from a file (first and second overloads): Read raster data directly from an OSS object, a MinIO bucket, or an HDFS file. The second overload lets you customize chunk and interleaving settings via storageOption.
Create from an array (third overload): Generate a raster object from a one-dimensional array of pixel values. The extent parameter is optional; chunk_table inside storageOption is required.

To check which file formats are supported, call ST_RasterDrivers.

Parameters

Parameter	Type	Description
`url`	cstring	Path of the OSS object, MinIO object, or HDFS file. See Object storage paths for the supported URL formats.
`storageOption`	cstring	JSON string that specifies how chunks are stored for the raster pyramid. See the `storageOption` fields table below.
`data`	anyarray	Raster pixel values as a one-dimensional array. The number of elements must equal the number of columns multiplied by the number of rows.
`width`	integer	Number of columns in the raster.
`extent`	geometry	Spatial extent of the raster, represented as a geometry. Optional.

storageOption fields

Field	Type	Format	Default	Description
`chunkdim`	string	`(w,h,b)`	Same as the source object	Size of each chunk used to store pyramid data.
`interleaving`	string	—	`bsq`	Band interleaving method. Valid values: `bip` (band interleaved by pixel, BIP), `bil` (band interleaved by line, BIL), `bsq` (band sequential, BSQ), `auto` (determined automatically).
`chunk_table`	string	—	None	Name of the chunk table. Required when creating a raster object from an array.

Change chunkdim or interleaving only when the defaults don't meet your needs:

Set interleaving to bip for multiband RGB rendering.
Set chunkdim to your target tile size (for example, (256,256,3)) when the source image uses a different chunk layout, such as 1 row x n columns.

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 bucket

Specify the host and port in the URL.

SELECT ST_CreateRast('OSS://<ak>:<ak_secret>@10.0.XX.XX: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.XX.XX:8020/path/image.tif');

Customize chunk and interleaving options

Set chunkdim to (256,256,3) and let the function choose the interleaving method automatically.

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

Create a raster object from a NetCDF file with subsets

Append the subset name (hcc) to the file path with a colon.

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

Create a raster object from an array

Pass pixel values as a one-dimensional array. The number of elements equals columns x rows. Specify chunk_table in storageOption and, optionally, a spatial extent.

-- Create from a fixed array with a spatial 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 multiple records into a raster object
SELECT ST_FixedRid(
  ST_CreateRast(
    (SELECT array_agg(value) FROM point_table),
    300,
    '{"chunktable":"rbt"}'
  )
);

What's next

After creating a raster object, build a pyramid to enable efficient multi-scale rendering and querying. See ST_BuildPyramid and ST_MetaData to inspect the raster metadata.