Overview
The unstructured data Catalog (Volume-type Catalog) is used to centrally manage unstructured data such as logs, images, audio/video, and PDFs. DataBuddy uses the Volume asset type to bring unstructured files into the same three-level namespace as tables and models, enabling unified permission governance and lineage tracking.
This document describes how to create a Volume-type Catalog, create Volumes under it, and upload, browse, and preview files.
Prerequisites
You have activated the DataBuddy service and completed workspace initialization.
The current account has permission to create Catalogs in the target workspace.
Use Limits
Limit | Description |
Supported Region | All regions that support DataBuddy |
Storage Type | Currently, only Tencent Cloud COS is supported. For managed volumes, the platform directly manages the underlying storage. External volumes must be created based on External Location. |
Supported Preview Type | CSV, Text, PDF (other file types support download only) |
Volume Search | Global data search supports searching Volume names, descriptions, tags, and the names of folders and files within Volumes. |
Folder Creation | Folders can be created within a Volume. When a file with a duplicate name is uploaded, it is automatically overwritten. |
Creating a Volume Catalog
Step 1: Enter the Data Catalog
2. Select Data Catalog in the left sidebar.
Step 2: Create a Volume Catalog
1. Click + Create Data Catalog at the top of the left directory tree.
2. Configure the parameters in the Create Data Catalog dialog box:
Catalog Name: Required.
Catalog Source: Required. Select TCCatalog.
Catalog Type: Required. Select Native Catalog.
Catalog Purpose: Required. Select File Volume Directory.
Description: Optional. Up to 500 characters.
3. Click Confirm to complete the creation.
After successful creation, you will be directed to the Catalog details page, which includes the default Schema, similar to a structured data catalog.
Creating a Volume
A Volume is a container for unstructured files and is mounted under a Schema.
Step 1: Go to the Schema Details Page
1. On the Catalog details page, click the target Schema name to go to the Schema details page.
2. Click Create Data Object in the upper-right corner.
Step 2: Enter Volume Information
In the dialog, select the Volume type:
Volume Type | Description |
Managed Volume (Managed Volume) | The platform allocates the storage path. You only need to enter the Volume name and description. |
External Volume (External Volume) | |
Enter the following information:
Volume Name: Required. Must be unique within the current Schema.
Volume Storage Type: Cloud-managed or external.
External Location: Required only for external Volumes. Select a registered External Location from the drop-down list.
Description: Optional.
Click OK to complete the creation. After the creation is successful, you will be directed to the Volume details page.
Managing Files in a Volume
The Overview Tab on the Volume details page provides file and folder management capabilities.
Uploading Documents
In the upper-right corner of the Volume details page, click Upload Data to go to the unstructured data upload page. For detailed operations, see Upload Local Files to a Volume. Tip
File upload is performed by the frontend directly calling the COS API, without the need to select compute resources. Files with duplicate names will automatically overwrite the original files.
Creating Folder
1. On the Overview Tab of the Volume details page, click Create Folder.
2. Enter the folder name in the pop-up window.
3. Click OK to complete the creation.
Folders support nesting. Paths are displayed in the format /Volumes/<catalog>/<schema>/<volume>/<directory>/.... You can copy the full path from the breadcrumb above the list.
Deleting Files and Folders
Select the target files or folders in the file list, and click Delete in the list. You can also choose the batch delete operation from the More drop-down menu at the top.
Deleting a non-empty folder will also delete all of its contents.
Warning
Deleted files and folders cannot be recovered. Before deletion, confirm that no dependent tasks or downstream references exist.
File Search
Enter a file or folder name in the search box above the file list to perform a real-time fuzzy search.
File Preview
In the file list, click the preview icon to go to the file preview page.
Supported types: CSV, Text, and PDF.
Actions: Download, Preview, and Delete.
For file types that do not support preview, only metadata is displayed. You can download the file to view it locally.
File Path Format
Files in a Volume follow a unified path format:
/Volumes/<catalog>/<schema>/<volume>/<directory>/<file>
For example:
/Volumes/ops_catalog/raw_logs/access_log/2026-06-06/access.log
This path can be directly referenced by SQL, Python code, and Notebook:
with open("/Volumes/ops_catalog/raw_logs/access_log/2026-06-06/access.log") as f:
data = f.read()
Volume Details Page Information
Display: storage path, creation time, creator, data modification time, and modifier.
Permission Management
The permission model of a Volume is consistent with that of tables and models. Permissions can be granted independently at the Catalog / Schema / Volume level.
Volume-Level Permission Points
Permission Point | Description |
read
| Read files in a Volume (including download and preview) |
write
| Write/update files in a Volume (including upload and overwrite) |
delete
| Delete files in a Volume |
create volumes
| Create a Volume in the associated Schema. |
all
| Grant all permissions listed above. |
grant
| Can grant permissions to others (manage all permissions listed above) |
Tip
Volume permissions also have dependencies. When granting read / write / delete, ensure that the user already has the use catalog permission on the owning Catalog and the use schema permission on the owning Schema. Otherwise, the user cannot locate the Volume.
Configuring Volume Permissions
1. Go to the Permissions Tab on the Volume details page.
2. Click Add Authorization and select the authorized principal (user/user group).
3. Select a preset permission (Read or Edit) or select specific Volume permissions.
4. Click Confirm to complete the authorization.
Only the root account, Volume owners, and users with the grant permission can perform authorization. For other users, the authorization button is disabled.
Transferring Volume Ownership
1. On the right side of the Volume details page, click the pencil icon next to Business Information > Asset Owner.
2. Select a new owner.
3. In the dialog box, confirm the message: "If you are not the creator of this Volume, you will no longer have management permissions on this Volume after the transfer."
Business Tags
On the right side of the Volume details page, click the pencil icon next to Business Information > Tag to add multiple governance tags to the Volume in key:value format. For detailed rules, see Governance Tags. FAQs
Q: What is the difference between a managed Volume and an external Volume?
A:
Managed Volume: The underlying storage is allocated by the platform (using the default default storage space), so you do not need to prepare a COS path in advance. This option is suitable for new projects and testing scenarios.
External Volume: Created based on a registered External Location, it reuses an external COS bucket path to facilitate cross-workspace sharing or integration with existing data. For details, see External Data Management. Q: Why do I not need to select a compute resource when uploading files?
A: Volume file upload is completed by the frontend directly calling the COS API, without going through the compute engine. Therefore, the upload process does not consume compute resources.
Q: Will deleting a Volume also delete the underlying COS files?
A:
Managed Volume: After a Volume is deleted, the platform also cleans up the files under the corresponding COS path.
External Volume: Deleting a Volume only removes its metadata registration in DataBuddy and does not delete the COS files associated with the External Location.
Q: Can files in a Volume be directly read by SQL?
A: Yes. Volume paths (/Volumes/<catalog>/<schema>/<volume>/...) can be directly read in Spark SQL, Python, and Notebook. For example, to read Parquet files in a Volume using Spark: spark.read.parquet("/Volumes/ops_catalog/raw_logs/event/").
References