文件与卷¶

Volume 用于管理文档、图片、音视频等非结构化数据。Folder 组织 Volume 内的层级，File 保存文件元数据并提供下载或预览入口：

Database → Volume → Folder（可嵌套）→ File

Python 使用 RawClient 的 snake_case 方法；Go 使用 RawClient 的 PascalCase 方法。本页示例沿用 Catalog 中创建的 Python client。

创建 Volume 和 Folder¶

volume = client.create_volume(
    {
        "database_id": 201,
        "name": "source_documents",
        "description": "Documents awaiting processing",
    }
)
folder = client.create_folder(
    {"name": "2026", "volume_id": "vol-1", "parent_id": ""}
)

请使用创建响应中的真实 ID 替换示例 ID。创建子 Folder 时，把父 Folder ID 传给 parent_id。Go 对应方法为 CreateVolume 和 CreateFolder。

get_volume_full_path / GetVolumeFullPath 可根据 Volume 或 Folder ID 解析完整路径，适合在删除或批量写入前再次确认目标。

两条上传路径¶

SDK 提供的文件相关方法服务于两种不同流程，不要混用：

目标	Python 方法	结果
将非结构化本地文件导入 Volume	`SDKClient.import_local_file_to_volume`、`import_local_files_to_volume`	上传文件并返回导入结果
暂存本地文件，随后按表格导入	`RawClient.upload_local_file*`	返回 `conn_file_ids`，供预览和表导入使用
直接调用 Catalog 文件元数据接口	`create_file`、`upload_file`	低层操作；调用方必须准确构造服务端要求的元数据

一般业务代码应优先使用 SDKClient 的高层 Volume 导入方法：

from moi import SDKClient

sdk = SDKClient(client)
result = sdk.import_local_file_to_volume(
    "/data/handbook.docx",
    "vol-1",
    {"filename": "handbook.docx", "path": "handbook.docx"},
    {"by": ["name", "md5"], "strategy": "skip"},
)

批量导入使用 import_local_files_to_volume(paths, volume_id, metadata, dedup)。文件路径列表与元数据列表应一一对应。dedup 的字段和策略使用 SDK 支持的值；不要自造策略名。

Go SDK 通过 UploadConnectorFile 执行带过滤、去重或 Table 配置的高级上传，通过 UploadFile 调用 Catalog 的简单上传接口。UploadConnectorFile 与 file.go 中的 UploadFile 不是同一个操作。

列出和查找文件¶

list_files / ListFiles 支持分页和条件过滤。Python 高层客户端还提供按名称和 Volume 查找：

page = client.list_files(
    {"keyword": "", "common_condition": {"page": 1, "page_size": 20}}
)
matches = sdk.find_files_by_name("handbook", "vol-1")

遍历时使用响应中的总数或分页信息停止，不要以“本页少于 page_size”之外的猜测替代服务端分页语义。

下载与预览¶

get_file_download_link / GetFileDownloadLink 返回临时签名下载地址。
get_file_preview_link / GetFilePreviewLink 返回浏览器或应用可用的预览地址。
get_file_preview_stream / GetFilePreviewStream 返回流式预览地址。
get_file / GetFile 读取名称、大小、类型等元数据。

预览能力取决于文件类型和后端处理状态。签名 URL 可能过期，不应写入数据库供长期复用；需要下载时应重新获取。

更新、清理与删除¶

update_volume、update_folder 和 update_file 可更新各自允许的元数据。删除操作具有不同范围：

操作	影响
`delete_file`	永久删除一个 File
`clean_folder`	删除 Folder 内所有文件和子 Folder，但保留该 Folder
`delete_folder`	删除整个 Folder 树
`delete_volume`	删除 Volume 及其全部 Folder 和 File

删除前调用 get_folder_ref_list 或 get_volume_ref_list 检查引用，并确认目标 ID 和完整路径。删除引用记录时才使用 delete_file_ref；它不能替代按 File ID 删除实际文件。