All Products
Search

This Product

    PolarDB:ST_CreateRast

    Document Center

    PolarDB:ST_CreateRast

    Last Updated:Mar 28, 2026

    Creates a raster object from a file stored in an OSS bucket, a MinIO bucket, or an HDFS file. Also creates 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);

    Parameters

    ParameterDescription
    urlThe path of the source file. For the supported path formats, see Object storage paths.
    storageOptionA JSON string that specifies the chunk storage options for the raster pyramid.
    dataA one-dimensional array representing the raster. The array length must equal the number of columns multiplied by the number of rows.
    widthThe number of columns in the raster.
    extent(Optional) The three-dimensional space represented by using a geometry.

    storageOption fields

    FieldTypeFormatDefaultDescription
    chunkdimString(w,h,b)Same as the chunk size in the source fileThe size of each chunk used to store raster data.
    interleavingString—bsqThe interleaving method. Valid values: bip (band interleaved by pixel), bil (band interleaved by line), bsq (band sequential), auto (determined automatically).
    chunk_tableString—NoneThe name of the chunk table. Required when creating a raster object from a one-dimensional array.

    Usage notes

    Override the defaults for chunkdim and interleaving only in the following cases:

    • RGB multiband viewing: If interleaving is bsq but the raster will be rendered using multiband RGB combination, set interleaving to bip.

    • Chunk size mismatch: If the source image has chunks of 1 row × n columns but you need 256 × 256 chunks, set chunkdim to the requested chunk size.

    To get a list of supported data formats, call the ST_RasterDrivers function.

    Examples

    All examples use ST_CreateRast to create raster objects from different storage backends.

    -- Create a raster object from an OSS file using AccessKey credentials and an internal endpoint.
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 using 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 using a username in the URL.
SELECT ST_CreateRast('HDFS://<user_name>@10.0.XX.XX:8020/path/image.tif');

-- Create a raster object with custom 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"}');

-- Create a raster object from a NetCDF file and select the hcc subset.
SELECT ST_CreateRast('OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc');

-- Create a raster object from a one-dimensional array with a 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)));

-- Create a raster object by aggregating values from a table using array_agg.
SELECT ST_FixedRid(ST_CreateRast((SELECT array_agg(value) FROM point_table), 300, '{"chunktable":"rbt"}'));