COPY FILES INTO VOLUME

功能概述

把一个 Volume 中已有的文件原样复制到另一个 Volume（保留文件内容，不解析、不转换格式）。常用于在外部 Volume（OSS/COS/S3）、Managed Volume、USER VOLUME、TABLE VOLUME 之间搬运文件，例如把对象存储中的归档文件转存到表暂存区再导入，或在不同 Volume 之间做备份。

与

COPY INTO VOLUME

COPY INTO VOLUME

（把表或查询结果导出为文件）不同：本命令的源和目标都是 Volume，按文件原样复制，不涉及表数据，也不指定

FILE_FORMAT

FILE_FORMAT

。

语法

COPY FILES INTO { VOLUME <volume_name> | TABLE VOLUME <table_name> | USER VOLUME } [ SUBDIRECTORY '<dest_path>' ] FROM { VOLUME <volume_name> | TABLE VOLUME <table_name> | USER VOLUME } [ SUBDIRECTORY '<src_path>' ] [ FILES = ( '<file_name>' [, ...] ) | REGEXP = '<pattern>' ]

参数说明

目标 Volume（
```
INTO
```
INTO
）：三种 Volume 类型任选其一。
- ```
VOLUME <volume_name>
```
  VOLUME <volume_name>
  ：外部 Volume（OSS/COS/S3）或 Managed Volume。
- ```
TABLE VOLUME <table_name>
```
  TABLE VOLUME <table_name>
  ：指定表的暂存 Volume。
- ```
USER VOLUME
```
  USER VOLUME
  ：当前用户的 USER VOLUME。
- ```
SUBDIRECTORY '<dest_path>'
```
  SUBDIRECTORY '<dest_path>'
  ：可选，目标子目录；省略时写入目标 Volume 根目录。
源 Volume（
```
FROM
```
FROM
）：三种 Volume 类型任选其一，可与目标类型不同（支持跨类型复制）。
- ```
SUBDIRECTORY '<src_path>'
```
  SUBDIRECTORY '<src_path>'
  ：可选，只复制源 Volume 指定子目录下的文件。
文件筛选（
```
FILES
```
FILES
与
```
REGEXP
```
REGEXP
二选一，均可省略）：
- ```
FILES = ( '<file_name>' [, ...] )
```
  FILES = ( '<file_name>' [, ...] )
  ：按文件名精确指定，文件名相对源（子）目录。列表中任一文件不存在，整个操作失败并报
```
CZLH-70002: File not found
```
  CZLH-70002: File not found
  。
- ```
REGEXP = '<pattern>'
```
  REGEXP = '<pattern>'
  ：按文件相对路径做正则匹配。
⚠️ 注意：正则参数必须写成
```
REGEXP = '<pattern>'
```
REGEXP = '<pattern>'
（带等号），与导入语法
```
COPY INTO TABLE ... REGEXP '<pattern>'
```
COPY INTO TABLE ... REGEXP '<pattern>'
（不带等号）写法不同。
💡 提示：同时省略
```
FILES
```
FILES
和
```
REGEXP
```
REGEXP
时，会递归复制源（子）目录下的全部文件。

返回结果说明

执行成功后返回单列

file

file

，列出每个被复制文件在源 Volume 中的相对路径。

注意事项

FILES
FILES
关键字必填：
```
COPY
```
COPY
与
```
INTO
```
INTO
之间必须写
```
FILES
```
FILES
。写成
```
COPY INTO VOLUME ... FROM VOLUME
```
COPY INTO VOLUME ... FROM VOLUME
会被当作表导出语法而报语法错误。
默认覆盖：目标 Volume 中同名文件会被覆盖，重复执行幂等；本命令没有
```
OVERWRITE
```
OVERWRITE
关键字。
目标路径只保留文件名：复制到目标时不保留源子目录层级，文件落在目标
```
SUBDIRECTORY
```
SUBDIRECTORY
之下。
源文件不存在即失败：
```
FILES
```
FILES
列表里任一文件在源中不存在，整条命令失败。

使用示例

前置准备：创建两个 Volume，并往源 Volume 放入文件。

CREATE VOLUME src_vol; CREATE VOLUME dst_vol; -- PUT 需在客户端工具（如 sqlline）中执行；Studio 运行在服务端，无法读取本地文件，不支持 PUT PUT '/tmp/orders_2024_01.csv' TO VOLUME src_vol; PUT '/tmp/orders_2024_02.csv' TO VOLUME src_vol; PUT '/tmp/orders_2024_03.csv' TO VOLUME src_vol SUBDIRECTORY '2024/';

复制单个文件（最简形式）：

COPY FILES INTO VOLUME dst_vol FROM VOLUME src_vol FILES = ('orders_2024_01.csv');

file -------------------- orders_2024_01.csv

复制多个文件到指定子目录：

COPY FILES INTO VOLUME dst_vol SUBDIRECTORY 'archive/' FROM VOLUME src_vol FILES = ('orders_2024_01.csv', 'orders_2024_02.csv');

file -------------------- orders_2024_01.csv orders_2024_02.csv

用正则匹配复制（注意

REGEXP =

REGEXP =

带等号）：

COPY FILES INTO VOLUME dst_vol SUBDIRECTORY 'archive/' FROM VOLUME src_vol REGEXP = 'orders_2024_0[12].csv';

file -------------------- orders_2024_01.csv orders_2024_02.csv

从源 Volume 的子目录复制（返回的

file

file

是源相对路径）：

COPY FILES INTO VOLUME dst_vol SUBDIRECTORY 'from_2024/' FROM VOLUME src_vol SUBDIRECTORY '2024/' FILES = ('orders_2024_03.csv');

file -------------------- 2024/orders_2024_03.csv

不指定筛选条件时，递归复制源 Volume 下的全部文件：

COPY FILES INTO VOLUME dst_vol SUBDIRECTORY 'backup/' FROM VOLUME src_vol;

file -------------------- 2024/orders_2024_03.csv orders_2024_01.csv orders_2024_02.csv

跨 Volume 类型复制——把外部 Volume 的文件复制到 USER VOLUME：

COPY FILES INTO USER VOLUME SUBDIRECTORY 'download/' FROM VOLUME my_oss_volume FILES = ('orders_2024_01.csv');

把文件复制到表的 TABLE VOLUME 暂存区，便于随后用 COPY INTO 导入：

COPY FILES INTO TABLE VOLUME orders SUBDIRECTORY 'incoming/' FROM VOLUME src_vol FILES = ('orders_2024_01.csv'); -- 从 TABLE VOLUME 导入表中 COPY INTO orders FROM TABLE VOLUME orders USING CSV OPTIONS('header' = 'true') FILES ('orders_2024_01.csv');

用

SHOW VOLUME DIRECTORY

SHOW VOLUME DIRECTORY

验证复制结果：

SHOW VOLUME DIRECTORY dst_vol SUBDIRECTORY 'archive/';

relative_path size ----------------------------- ---- archive/orders_2024_01.csv 36 archive/orders_2024_02.csv 36