Use ST_ImportGLTF to import a glTF file into a database - PolarDB

Imports a GL Transmission Format (glTF) file into a GanosBase database as sfmesh data.

Syntax

Syntax 1 — Import from an object storage URL:

boolean ST_ImportGLTF(text table_name, text url, text id, text options default '{}');

Syntax 2 — Import from binary content:

boolean ST_ImportGLTF(text table_name, bytea content, text id, text options default '{}');

Returns true if the import succeeds.

Parameters

Parameter	Description
`table_name`	The name of the glTF primary table. Also used as the prefix for sharded tables generated during the import.
`url`	The object storage path to the glTF file (for example, an Object Storage Service (OSS) bucket path). For path format details, see Object storage paths.
`id`	The ID to assign to the imported glTF file.
`content`	The binary (`bytea`) content of the glTF file. Use this parameter to import from memory instead of an object storage path.
`options`	A JSON string of import options. Defaults to `'{}'`. See the Options fields table below.

Options fields

Field	Type	Default	Example	Description
`schema`	String	`public`	`postgres`	The database schema for the generated tables.
`flip_y_z`	Boolean	`true`	`false`	Exchanges y-axis and z-axis values on import. By default, the y-axis of glTF is vertical while the z-axis is vertical in GanosBase. Note: axis exchange only applies when the glTF file uses a y-up coordinate system.
`split_meshgeom`	Boolean	`false`	`true`	Splits geometry data into a separate geometry table named `[table_name]_meshgeom`. Geometry data in the primary table references the rows in the geometry table. Use this option to avoid oversized records when importing models with many complex geometries.
`split_texture`	Boolean	`false`	`true`	Splits embedded image textures into a separate texture table named `[table_name]_texture`. Texture data in the primary table references the rows in the texture table. Use this option to avoid oversized records when importing models with many textures, such as oblique photographs.
`sfmesh_column`	String	`gltf_data`	`my_data`	The name of the sfmesh data column in the primary table.
`gltf_id_column`	String	`gltf_id`	`my_id`	The name of the data ID column in the primary table.

When importing multiple models into the same table, each model must have a unique id. Duplicate IDs result in duplicate geometry or texture records. Splitting geometry and textures into separate tables does not interfere with each other — both options can be enabled at the same time.

Limitations

Limitation	Detail
Supported data type	Only sfmesh data (meshes) is imported. Camera, skeleton, and animation data is silently ignored.
Mesh method	Only meshes built with the triangulation method are supported.
Compression	Draco-compressed data is not supported. The import fails if the file uses Draco compression.
Storage mode	Only the fully embedded mode is supported. Files that rely on binary extensions or texture extensions fail to import.

Generated tables

After a successful import, the function creates or updates the following tables.

Primary table

The primary table stores the sfmesh data. Its name is set by table_name. Only the data column and the ID column are populated on insert; all other fields are auto-configured.

Field	Type	Remarks
`id`	serial	Primary key, auto-incremented.
`[gltf_id_column]`	text	Data ID. Column name defaults to `gltf_id`.
`[sfmesh_column]`	sfmesh	The sfmesh data. Column name defaults to `gltf_data`.

Texture table (when split_texture is true)

Created only when the glTF file contains embedded image textures. Table name: [table_name]_texture.

Field	Type	Remarks
`id`	serial	Primary key.
`gltf_id`	text	Data ID. Must be `gltf_id`.
`texture_id`	text	Index of the texture in the original glTF file.
`texture`	texture	The texture data.

If the glTF file stores textures as URLs rather than embedded binary data, split_texture has no effect. If no embedded textures exist, no texture table is created.

Geometry table (when split_meshgeom is true)

Table name: [table_name]_meshgeom.

Field	Type	Remarks
`id`	serial	Primary key.
`gltf_id`	text	Data ID. Must be `gltf_id`.
`meshgeom_id`	text	Index of the mesh in the original glTF file.
`meshgeom`	meshgeom	The geometry data.

Examples

Import from OSS

The most common pattern: import a glTF file stored in an OSS bucket.

SELECT ST_ImportGLTF(
    'test_gltf',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/path_to_gltf.gltf',
    'my_gltf'
);

---------
 t

Replace <ak> and <ak_secret> with your Alibaba Cloud AccessKey ID and AccessKey Secret.

Import with custom options

Split textures into a separate table and disable axis flipping:

SELECT ST_ImportGLTF(
    'buildings',
    'OSS://<ak>:<ak_secret>@oss-cn-beijing-internal.aliyuncs.com/mybucket/building.gltf',
    'building_001',
    '{"split_texture": true, "flip_y_z": false}'
);

What's next

Query the imported data using SELECT * FROM test_gltf;
For object storage path formats, see Object storage paths.