Lakehouse Volume 文件管理指南

概述

Volume 是云器 Lakehouse 提供的文件存储与管理对象，支持内部 User Volume 和外部 External Volume。通过 Volume，你可以直接在 Lakehouse 中上传、下载、列出和删除文件，无需借助外部工具。本指南按业务场景分类，帮助你快速掌握 Volume 的文件操作方法。

涉及的 SQL 命令

命令	用途	适用场景
`PUT 'local_path' TO USER VOLUME FILE 'filename'` PUT 'local_path' TO USER VOLUME FILE 'filename'	上传文件	将本地 CSV/Parquet 导入 Volume
`LIST USER VOLUME 'path'` LIST USER VOLUME 'path'	列出文件	查看 Volume 目录结构
`GET FROM USER VOLUME FILE 'filename' TO 'local_path'` GET FROM USER VOLUME FILE 'filename' TO 'local_path'	下载文件	将 Volume 文件导出到本地
`REMOVE USER VOLUME FILE 'filename'` REMOVE USER VOLUME FILE 'filename'	删除文件	清理 Volume 中的临时文件
`SELECT * FROM VOLUME 'path'` SELECT * FROM VOLUME 'path'	查询文件	直接读取文件内容（支持 CSV/JSON/Parquet）

前置准备

以下示例使用 Lakehouse 内置的 User Volume：

-- 查看当前用户的 Volume 路径 SELECT CURRENT_USER(); -- User Volume 文件协议格式: volume:user://~/filename

上传文件到 Volume

使用

PUT

PUT

命令将本地文件上传到 User Volume。

-- 上传本地 CSV 文件到 Volume PUT '/tmp/data_export.csv' TO USER VOLUME FILE 'data_export.csv';

结果说明：

文件上传成功后，可通过
```
LIST
```
LIST
命令验证。
上传的文件仅当前用户可见（User Volume 隔离）。

列出 Volume 文件

使用

LIST

LIST

命令查看 Volume 中的文件和目录。

-- 列出 User Volume 所有文件 LIST USER VOLUME; -- 按子目录过滤 LIST USER VOLUME SUBDIRECTORY 'data/'; -- 按正则表达式过滤 LIST USER VOLUME REGEXP = '.*\.csv';

返回列说明：

列名	说明
`relative_path` relative_path	文件在 Volume 中的相对路径
`url` url	文件的对象存储完整 URL
`size` size	文件大小（字节）
`last_modified_time` last_modified_time	文件最后修改时间（UTC）

下载文件从 Volume

使用

GET

GET

命令将 Volume 中的文件下载到本地。

-- 下载 Volume 文件到本地 GET FROM USER VOLUME FILE 'data_export.csv' TO '/tmp/downloaded_data.csv';

适用场景：

数据备份到本地
与外部系统交换文件

删除 Volume 文件

使用

REMOVE

REMOVE

命令删除 Volume 中不再需要的文件。

-- 删除 Volume 文件 REMOVE USER VOLUME FILE 'data_export.csv';

⚠️ 注意：

REMOVE

REMOVE

操作不可逆，删除后无法通过 Time Travel 恢复文件。

直接查询文件内容

Lakehouse 支持直接查询 Volume 中的文件，无需先导入到表。

-- 查询 User Volume 中的 CSV 文件（带列定义，表头正确显示） SELECT * FROM USER VOLUME (id INT, name STRING, value DOUBLE) USING CSV OPTIONS ('header' = 'true') FILES ('data_export.csv'); -- 不带列定义时，列名自动生成为 f0, f1, f2... SELECT * FROM USER VOLUME USING CSV OPTIONS ('header' = 'false') FILES ('data_export.csv'); -- 查询 External Volume 中的文件 SELECT * FROM VOLUME my_volume (id INT, name STRING, value DOUBLE) USING CSV OPTIONS ('header' = 'true') SUBDIRECTORY 'data/';

支持的格式：

CSV / TSV
JSON / JSONL
Parquet / ORC
Avro

💡 提示：直接查询适合临时数据探索。频繁查询建议先

COPY INTO

COPY INTO

导入到表中。

清理测试数据

完成 Volume 验证后，建议清理上传的文件：

-- 删除测试文件 REMOVE USER VOLUME FILE 'data_export.csv';

注意事项

路径格式：
```
LIST
```
LIST
/
```
SELECT FROM VOLUME
```
SELECT FROM VOLUME
使用
```
USER VOLUME
```
USER VOLUME
、
```
TABLE VOLUME table_name
```
TABLE VOLUME table_name
、
```
VOLUME schema.vol_name
```
VOLUME schema.vol_name
关键字，不使用字符串路径。
文件大小限制：单文件上传建议不超过 1GB，超大文件建议使用外部存储连接。
权限隔离：User Volume 仅创建者可见，External Volume 可配置共享权限。
查询性能：直接查询 Volume 文件性能低于查询表，生产环境建议先导入。
并发写入：
```
PUT
```
PUT
不支持并发写入同一文件，需确保文件锁或串行操作。