# 目录、数据库、表、卷和文件

Product SDK 将数据资源组织在工作区范围内。先取得 SDK 返回的工作区对象，再从目录进入数据库、表、卷、文件夹和文件；不要在应用中拼接资源路径或根据显示名称猜测资源 ID。

## 选择起点

| 要完成的任务 | 从哪里开始 | 结果 |
| --- | --- | --- |
| 使用已有的目录、数据库或表 | 工作区对象和已确认的资源 ID | 对应的目录、数据库或表对象 |
| 查找目录，不存在时创建 | 工作区的目录准备方法 | 目录对象；缺少目录时会产生创建操作 |
| 查找卷，不存在时创建 | 数据库的卷准备方法 | 卷对象；缺少卷时会产生创建操作 |
| 上传已有的字节内容 | 卷对象 | 文件对象 |

“按名称准备”会查找完全匹配的可见资源；找不到时会创建资源。自动化脚本使用这类方法前，应确认名称、目标工作区和写入权限。

## SDK 调用

以下示例从已经取得的工作区对象开始，依次取得目录、数据库和卷，再上传调用方已持有的字节内容：

:::::{tab-set}

::::{tab-item} Go

```go
catalog, err := workspace.PrepareCatalog(ctx, catalogName)
database, err := catalog.PrepareDatabase(ctx, databaseName)
volume, err := database.PrepareVolume(ctx, volumeName)
file, err := volume.UploadBytesHandle(ctx, fileName, fileBytes)
```

::::

::::{tab-item} Python

```python
catalog = workspace.prepare_catalog(catalog_name)
database = catalog.prepare_database(database_name)
volume = database.prepare_volume(volume_name)
file = volume.upload_bytes_handle(file_name, file_bytes)
```

::::

:::::

`file` 是后续下载、预览或数据血缘操作使用的文件对象。上传调用已提交后，仍应根据返回结果确认文件可用状态。

## 管理表

通过目录和数据库对象浏览表，或使用已确认的表 ID 获取表对象。创建表时，调用方需要明确提供表名和列定义；SDK 不会根据展示名称、文件名或查询文本推断表结构。

创建、更新、清空或删除表会改变数据。将这些操作与只读浏览分开，并在调用前保留用于确认的目录、数据库和表信息。

## 管理卷和文件

卷用于组织文件资源，文件夹和文件都属于明确的卷作用域。上传时应由调用方提供文件名和字节内容；上传成功后保存返回的文件对象或文件 ID，以便后续预览、下载、删除或触发关联操作。

不要让应用根据本地目录自动发现文件、根据文件名推断目标卷，或把文件 URL 当作永久资源标识。文件来源、目标卷和后续写入操作都应由调用方明确选择。

## 语言方法对照

| 任务 | Go | Python |
| --- | --- | --- |
| 按名称准备目录 | `PrepareCatalog` | `prepare_catalog` |
| 按名称准备卷 | `PrepareVolume` | `prepare_volume` |
| 上传已有字节并取得文件对象 | `UploadBytesHandle` | `upload_bytes_handle` |

这些方法返回的 SDK 对象会保留已知的资源作用域。后续调用优先复用这些对象，不要回退为手写接口路径。

## 下一步

- [连接器、导入与导出任务](connectors-import-export)
- [使用 Product API 管理数据资源](../../../api/product-api/data-files-connectors/index)