# 管理卷和文件

将调用方已持有的字节内容上传到工作区内指定的卷，并保留返回的文件资源。随后可以用该资源预览或下载文件，也可以在同一卷中创建文件夹。

(sdk-ai-studio-volume-file-flow)=
## 任务流程

1. 调用方提供工作区、Catalog、数据库、卷名称、文件名和文件字节。
2. SDK 逐层查找同名 Catalog、数据库和卷；缺少任何一层时创建它。
3. SDK 上传字节并将文件附加到卷，返回文件资源。
4. 使用这个文件资源预览或下载内容；流式读取完成后关闭响应。

(sdk-ai-studio-volume-file-prepare)=
## 准备

| 需要的内容 | 在本页中的作用 |
| --- | --- |
| 已认证的客户端和已选择的工作区 | 确定上传的资源作用域。 |
| Catalog、数据库和卷名称 | 选择或创建文件的存放位置。 |
| 文件名和字节内容 | 上传文件。 |
| 写入权限 | 允许创建资源并附加文件。 |

本页不从本地目录自动发现文件，也不根据文件名推断目标位置。调用方需要先明确选择文件和目标工作区。

(sdk-ai-studio-volume-file-upload)=
## 上传到命名卷

下面的函数按名称准备保存位置后上传调用方已持有的字节。按名称准备不是只读查询；缺少同名 Catalog、数据库或卷时会产生创建操作。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
def upload_orders(workspace, csv_bytes):
    volume = workspace.prepare_data_volume("analytics", "sales", "landing")
    file = volume.upload_bytes_handle("orders.csv", csv_bytes)
    return volume, file
```

::::

::::{tab-item} Go
:sync: go

```go
import (
	"context"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func uploadOrders(ctx context.Context, workspace *sdk.WorkspaceHandle, csvBytes []byte) (*sdk.VolumeHandle, *sdk.FileHandle, error) {
	volume, err := workspace.PrepareDataVolume(ctx, "analytics", "sales", "landing")
	if err != nil {
		return nil, nil, err
	}
	file, err := volume.UploadBytesHandle(ctx, "orders.csv", csvBytes)
	if err != nil {
		return nil, nil, err
	}
	return volume, file, nil
}
```

::::

:::::

上传成功后，函数返回卷资源和文件资源。后续操作应继续使用它们，而不是从显示名称或本地路径拼接资源标识。

(sdk-ai-studio-volume-file-preview)=
## 创建文件夹并预览文件

使用上一步得到的卷资源创建文件夹，并使用文件资源打开预览流。预览和下载都是流式响应；读取结束后由调用方关闭它。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
folder, _ = volume.create_folder("staging")
preview = file.preview()
try:
    content = preview.read()
finally:
    preview.close()
_ = folder, content
```

::::

::::{tab-item} Go
:sync: go

```go
folder, _, err := volume.CreateFolder(ctx, "staging")
if err != nil {
	return err
}
preview, err := file.Preview(ctx)
if err != nil {
	return err
}
defer preview.Body.Close()
_ = folder
```

::::

:::::

(sdk-ai-studio-volume-file-result)=
## 结果确认

文件夹和文件资源都保持卷的作用域。按资源标识重新取得资源时，只使用创建、列表或调用方明确提供的标识。读取预览流不代表文件内容已被其他任务处理。

(sdk-ai-studio-volume-file-limit)=
## 限制

- 本地路径上传只适用于调用方已经选择的本地文件；字节已在应用内时，使用字节上传。
- 文件改名不会持久化修改名称，不要将改名调用当作操作完成。
- 删除文件、卷或清理文件夹会改变数据。执行前确认它们由当前操作创建或明确属于当前调用方。

(sdk-ai-studio-volume-file-next)=
## 下一步

- [创建数据传输任务](connectors-import-export.md)
- [管理 Catalog、数据库和表](catalog-tables.md)