Use ST_ImportFrom to import data from OSS, MinIO, or HDFS to a raster object - ApsaraDB RDS

Creates a raster object in Ganos and imports data from an Object Storage Service (OSS) object, Multi-Cloud Object Storage (MinIO) object, or Hadoop Distributed File System (HDFS) file into it.

To check which data formats are supported, call ST_RasterDrivers.

Syntax

raster ST_ImportFrom(cstring chunkTableName,
                     cstring url,
                     cstring storageOption default '{}',
                     cstring importOption default '{}');

Parameters

Parameter	Description
`chunkTableName`	The name of the chunk table. Must comply with Ganos table naming conventions.
`url`	The URL of the OSS object, MinIO object, or HDFS file. For the URL format for each storage type, see Object storage paths.
`storageOption`	A JSON string that controls how the raster object is stored. Defaults to `{}`.
`importOption`	A JSON string that controls the import process. Defaults to `{}`.

storageOption fields

Field	Type	Default	Description
`chunking`	Boolean	`true`	Specifies whether to store raster data as chunks.
`chunkdim`	string	Same as source	The chunk dimensions in `(w, h, b)` format. Takes effect only when `chunking` is `true`.
`compression`	string	`lz4`	The compression format. Valid values: `none`, `jpeg`, `zlib`, `png`, `lzo`, `lz4`, `snappy`, `zstd`, `jp2k`.
`quality`	integer	`75`	The image quality of the raster object after compression. Takes effect only when `compression` is `jpeg` or `jp2k`.
`interleaving`	string	Same as source	The band interleaving method. Valid values: `bip` (Band Interleaved by Pixel), `bil` (Band Interleaved by Line), `bsq` (Band Sequential).
`blockendian`	string	`NDR`	The byte order for data chunks. Valid values: `NDR` (little endian), `XDR` (big endian).
`celltype`	string	Same as source	The pixel type of the raster object. Valid values: `1bb`, `2bui`, `4bui`, `8bsi`, `8bui`, `16bsi`, `16bui`, `32bsi`, `32bui`, `32bf`, `64bsi`, `64bui`, `64bf`.

importOption fields

Field	Type	Default	Description
`mapping_oss_file`	Boolean	`false`	Specifies whether to map the OSS object to an in-memory file in Ganos. Enable this when the driver generates many small read requests against OSS, which degrades performance. The maximum file size for in-memory mapping is controlled by the ganos.raster.memory_oss_file_max_size Grand Unified Configuration (GUC) parameter.
`parallel`	integer	Same as `ganos.parallel.degree` GUC	The degree of parallelism during import. Valid values: 1–64.
`compute_stats`	Boolean	`false`	Specifies whether to calculate band statistics automatically during import.
`approx`	Boolean	`false`	Specifies whether to use sampling when calculating band statistics. If `true`, results may be less accurate.
`factor`	integer	`4`	The sampling factor. Each sampling unit covers `n` pixels. Takes effect only when `approx` is `true`.
`exclusive_nodata`	Boolean	`true`	Specifies whether to exclude nodata values.

Examples

All examples use the same function signature — only the URL scheme and option values differ by storage type and use case.

Import from OSS

-- Basic import: AccessKey ID, AccessKey secret, and endpoint embedded in the URL
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif'
);

-- Import into a specific schema
SELECT ST_ImportFrom(
    'schema.chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif'
);

Import from MinIO

-- MinIO URL includes host and port
SELECT ST_ImportFrom(
    'chunk_table',
    'MIO://<ak>:<ak_secret>@10.0.0.1:443/mybucket/data/image.tif'
);

Import from HDFS

-- HDFS URL includes the username and NameNode address
SELECT ST_ImportFrom(
    'chunk_table',
    'HDFS://<user_name>@10.0.0.1:8020/path/image.tif'
);

Import files with subsets

For multi-variable formats such as NetCDF and HDF5, append the subset identifier to the URL.

-- NetCDF: append subset name after a colon
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc'
);

-- HDF5: append dataset path after ://
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.hdf5://ds/hcc'
);

Control storage layout and parallelism

-- Set chunk dimensions to 128x128 pixels with 3 bands, disable compression
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif',
    '{"chunkdim": "(128,128,3)", "compression": "none"}'  -- storageOption
);

-- Set the degree of parallelism to 4 to speed up large imports
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc',
    '{}',
    '{"parallel": 4}'  -- importOption
);

-- Map the OSS object to an in-memory file to reduce small read overhead,
-- then import in parallel with 4 workers
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.nc:hcc',
    '{}',
    '{"parallel": 4, "mapping_oss_file": true}'  -- importOption
);

Calculate band statistics during import

-- Automatically calculate band statistics during import
SELECT ST_ImportFrom(
    'chunk_table',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/data/image.tif',
    '',
    '{"compute_stats": true}'  -- importOption
);