Manage file storage

Create and maintain root volumes and files in a database, and inspect file artifacts. A volume belongs to a database; for tables and table data, see Manage catalogs, databases, and tables.

In the console, the storage object available from the database plus button is a volume. In a volume file list, an item whose file_type is folder represents Open folder. See List files.

Prerequisites

• Prepare access to the target workspace. For general rules, see Prepare to call an API.

• Before creating a volume, determine its database.

• Before associating an uploaded file with a volume, obtain the file record created by upload and the target volume.

Call sequence

1. Identify the target database in the Catalog hierarchy. When you need a new storage location, create a root volume in that database and retain its ID.

2. Use the volume ID to list files and confirm the location. To add a sublevel, create a folder in the volume or an existing folder. A folder item in the list remains under the same volume; retain volume_id and provide parent_id on the next query.

3. After uploading a file, use the create-file operation to associate its existing file record with the target volume. Then inspect file details or the file list to confirm. Confirm a folder’s location before changing it.

4. Preview, download, or stream-read a file when you need to inspect its content. To inspect processing results for multiple files, batch-query file artifacts or data assets.

5. Before unlinking, emptying, or deleting, inspect target details and references. After deleting a volume, folder, or file, query available resources again to confirm the result.

API operations

Create and maintain volumes

What you need to do	API operation	Use it when
Create a volume	Create a volume	You determined the target database and need a root volume.
Get volume details	Get a volume	You need to confirm a target root volume’s current information.
Get a volume’s full path	Get volume path	You need to confirm the volume’s place in the Catalog hierarchy.
Update a volume	Update a volume	You need to change a volume’s name or description.
Delete a volume	Delete a volume	You handled files in the volume and need to remove the root volume.
List volume references	List volume references	You need to inspect references before changing or deleting a volume.

Manage folders

What you need to do	API operation	Use it when
Create a folder	Create a folder	You need to create a subfolder in a volume or existing folder.
Update a folder	Update a folder	You need to change folder information.
List folder references	List folder references	You need to inspect references before changing, emptying, or deleting a folder.
Empty a folder	Empty a folder	You need to remove content from the specified folder and its subfolders.
Delete a folder	Delete a folder	You confirmed that the target folder is no longer needed.

Upload, associate, and access files

What you need to do	API operation	Use it when
Upload a file	Upload a file	You first need to upload a file that is not associated with a volume.
Create a file	Create a file	You need to associate an existing file record with a specified volume.
List files	List files	You need to confirm files in a volume or open a folder item in the list.
Get file details	Get a file	You need current file information or a target for a subsequent operation.
Update a file	Update a file	You need to submit a file-update request.
Preview a file	Preview a file	You need to inspect file content inline.
Download a file	Download a file	You need to obtain file content.
Unlink files	Unlink files	You need to unlink a group of files in the same root volume.
Delete a file	Delete a file	You confirmed that the target file is no longer needed.
Trigger a file workflow	Trigger a file workflow	You need to trigger the workflow associated with a file.

Inspect processing results

What you need to do	API operation	Use it when
Query file artifacts	List file artifacts	You need file-artifact information by file ID.
Query a data asset	Get a data asset	You need a processed data asset by original file ID.
Batch-query file artifacts	Batch-resolve file artifacts	You need processing associations for multiple files in one query.
Batch-query data assets	Batch-get data assets	You need data assets for multiple original files in one query.

Confirm the result

Use volume details, file details, or the file list to confirm creation, association, and updates. File artifacts and data assets are the source of truth for file processing results.

Limitations and notes

• File lists must be filtered by exactly one volume_id; retain that volume_id when opening a folder item.

• Uploading a file does not automatically associate it with a volume; call the create-file operation afterwards.

• Unprocessed files do not appear in data-asset query results.

• Before deleting a volume, handle the files in it. A group of files to unlink must belong to the same root volume.

• The update-file API does not currently persist name changes. Do not treat a successful response as confirmation that the file name was updated.

Next steps

• Manage catalogs, databases, and tables

Last updated on Sep 3, 2026