管理卷和文件¶

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

任务流程¶

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

准备¶

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

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

上传到命名卷¶

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

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

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
}

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

创建文件夹并预览文件¶

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

Python

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

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

结果确认¶

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

限制¶

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

下一步¶

最后更新于 2026 年 9 月 1 日