Use ST_CreateRast to create a raster object from OSS HDFS or an array - ApsaraDB RDS

Creates a raster object from a file in Alibaba Cloud Object Storage Service (OSS), a MinIO (Multi-Cloud Object Storage) bucket, or a Hadoop Distributed File System (HDFS) path. Alternatively, generates a raster object from data in a one-dimensional array.

Syntax

-- Variant 1: Create from a storage path
raster ST_CreateRast(cstring url);

-- Variant 2: Create from a storage path with chunk and interleaving options
raster ST_CreateRast(cstring url, cstring storageOption);

-- Variant 3: Create from a storage path with chunk, interleaving, and import options
raster ST_CreateRast(cstring url, cstring storageOption, cstring createOption);

-- Variant 4: Generate from a one-dimensional array
raster ST_CreateRast(anyarray data, integer width, cstring storageOption, geometry extent);

Parameters

Variants 1, 2, and 3: Create from a storage path

Parameter	Type	Description
`url`	cstring	The path of the source file. Supports OSS, MinIO, and HDFS paths. For path format details, see Object storage paths.
`storageOption`	cstring	(Variants 2 and 3) A JSON string that controls how chunks and interleaving are stored in the raster pyramid. See storageOption fields.
`createOption`	cstring	(Variant 3 only) A JSON string that controls band statistics calculation during import. See createOption fields.

Variant 4: Generate from a one-dimensional array

Parameter	Type	Description
`data`	anyarray	Raster data as a one-dimensional array. The element count must equal the number of columns multiplied by the number of rows.
`width`	integer	The number of columns in the raster data.
`storageOption`	cstring	A JSON string that specifies chunk storage options. The `chunk_table` field is required for this variant. See storageOption fields.
`extent`	geometry	(Optional) The 3D spatial extent of the raster, represented as a geometry.

storageOption fields

Field	Type	Default	Description
`chunkdim`	string	Same as the original chunk size	The dimensions of each chunk in `(width,height,bands)` format, for example, `(256,256,3)`.
`interleaving`	string	`bsq`	The interleaving type of the raster object. 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	The name of the chunk table. Required when using Variant 4 to generate a raster object from an array.

Note

Change chunkdim or interleaving from their defaults only when necessary:

To view a raster as a multiband red, green, and blue (RGB) composite when the current interleaving is bsq, change it to bip.
If the source image has 1×n-column chunks but you need 256×256 chunks, set chunkdim to (256,256,3).

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 a sampling method to calculate statistics. When `true`, results may be approximate.
`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 statistical calculations.

Description

You can obtain the supported data types by using the ST_RasterDrivers function.

URL format by storage type:

Each storage type uses a different URL scheme:

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

For multi-dataset formats like NetCDF and HDF5, append the dataset name to the path:

NetCDF: image.nc:<dataset>
HDF5: image.hdf5://<group>/<dataset>

Examples

Create a raster object from an OSS file:

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

Create a raster object from a MinIO file:

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

Create a raster object from an HDFS file:

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

Set chunk dimensions and interleaving:

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:

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 file with a named dataset:

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 file with a named dataset:

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

Generate a raster object from an array:

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 using array_agg:

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

ApsaraDB RDS:ST_CreateRast