PUT 命令
PUT 命令用于将客户端本地文件上传到 Lakehouse 的 Volume 对象中，支持外部 Volume、TABLE VOLUME 和 USER VOLUME 三种目标类型。
执行方式
PUT 是客户端侧命令，由 Lakehouse 客户端工具负责读取本地文件并传输数据。支持以下执行方式：
语法
PUT 'local_path' [, 'local_path' [, ...]]
TO
{ VOLUME volume_name | TABLE VOLUME table_name | USER VOLUME }
[ SUBDIRECTORY 'dir' | FILE 'filename' ]
[ option_key = option_value ] ...
参数说明
| 参数 | 是否必填 | 说明 |
|---|
local_path
local_path | 是 | 本地文件路径。Linux/macOS 以 /
/ 开头；Windows 使用正斜杠分隔，路径含特殊字符时需用单引号括起。支持同时指定多个路径，以逗号分隔。 |
VOLUME volume_name
VOLUME volume_name | 三选一 | 上传到指定的外部 Volume。 |
TABLE VOLUME table_name
TABLE VOLUME table_name | 三选一 | 上传到指定表的 TABLE VOLUME 暂存空间。 |
USER VOLUME
USER VOLUME | 三选一 | 上传到当前用户的 USER VOLUME。 |
SUBDIRECTORY 'dir'
SUBDIRECTORY 'dir' | 否 | 指定目标子目录，文件名保持不变。与 FILE
FILE 互斥。 |
FILE 'filename'
FILE 'filename' | 否 | 指定目标文件名，可用于上传时重命名文件。与 SUBDIRECTORY
SUBDIRECTORY 互斥。 |
示例
示例 1：上传文件到 USER VOLUME
将本地文件上传到当前用户的 USER VOLUME 根目录：
PUT '/Users/Downloads/data.csv' TO USER VOLUME;
上传后查看文件是否已到位：
SHOW USER VOLUME DIRECTORY;
示例 2：上传到 USER VOLUME 并指定目标路径
将文件上传到 USER VOLUME 的子目录，并重命名：
PUT '/Users/Downloads/data.csv' TO USER VOLUME FILE 'import/data_2026.csv';
示例 3：上传到外部 Volume 并重命名
将本地压缩包上传到名为
hz_image_volume
hz_image_volume
的外部 Volume，并重命名：
PUT '/Users/Downloads/cats_and_dogs.zip' TO VOLUME hz_image_volume FILE 'catsdogs.zip';
示例 4：上传到 TABLE VOLUME 后导入表
将文件上传到表的暂存空间，再通过 COPY INTO 导入：
-- 上传文件到表的 TABLE VOLUME
PUT '/Users/Downloads/region.tbl' TO TABLE VOLUME tbl_region;
-- 查看暂存文件
SHOW TABLE VOLUME DIRECTORY tbl_region;
-- 从 TABLE VOLUME 导入数据
COPY INTO tbl_region FROM TABLE VOLUME tbl_region (id INT, name STRING)
USING CSV
OPTIONS (
'header' = 'true',
'lineSep' = '\n'
)
FILES ('region.tbl')
PURGE = TRUE;
注意事项
- 单个文件大小上限为 5 GB。
- 若目标 Volume 中已存在同名文件，系统会自动覆盖，上传前请做好备份。
SUBDIRECTORY
SUBDIRECTORY
和 FILE
FILE
不能同时使用。- 上传到外部 Volume 会产生对应云账号的对象存储写入费用。
- 执行 PUT 命令需要对目标 Volume 具有写入权限。
