COPY INTO VOLUME

功能概述

将表或查询结果导出到 Volume（外部 OSS/COS/S3 或内部 User/Table Volume）。适合数据归档、跨系统传输、生成供下游消费的文件。

语法

COPY INTO { VOLUME external_volume_name | TABLE VOLUME table_name | USER VOLUME } SUBDIRECTORY '<path>' FROM { [schema.]<table_name> | ( <query> ) } FILE_FORMAT = ( TYPE = { CSV | PARQUET | JSON } [ formatTypeOptions ] ) [ copyOptions ]

参数说明

VOLUME：指定目标 Volume 类型。
- ```
VOLUME external_volume_name
```
  VOLUME external_volume_name
  ：外部 Volume（OSS/COS/S3）。需提前创建 External Volume。
- ```
TABLE VOLUME table_name
```
  TABLE VOLUME table_name
  ：表级 Volume，与指定表关联。
- ```
USER VOLUME
```
  USER VOLUME
  ：用户级 Volume，每个用户自动拥有。
  -- 1. 将数据导出到外部 Volume COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV); -- 2. 将数据导出到 User Volume COPY INTO USER VOLUME SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV); -- 3. 将数据导出到 Table Volume COPY INTO TABLE VOLUME birds SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV);
SUBDIRECTORY：指定子路径，参数必须填写。例如：
```
subdirectory 'month=02'
```
subdirectory 'month=02'
。
FROM：支持直接导出表中数据，或直接写 query 查询结果集。
-- 直接指定表 COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV); -- 将 SQL 结果集导出 COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM (select * from birds limit 1) file_format = (type = CSV);
formatTypeOptions：文件格式，支持 CSV、TEXT、PARQUET、JSON。其中 JSON 导出的格式是 JSON LINE。
- CSV 格式支持的参数：
  - ```
  sep
```
  sep
  ：列分隔符，默认为
```
  ,
```
  ,
  。
- ```
compression
```
    compression
    ：配置文件压缩格式，如
```
gzip
```
    gzip
    ,
```
zstd
```
    zstd
    ,
```
zlib
```
    zlib
    。
  - ```
  lineSep
```
  lineSep
  ：行分隔符，默认值为
```
  \n
```
  \n
  。
- ```
quote
```
    quote
    ：用于包裹包含特殊字符的字段，默认值为
```
"
```
    "
    。
  - ```
  header
```
  header
  ：是否输出表头，默认为
```
  false
```
  false
  。
- ```
timeZone
```
    timeZone
    ：配置时区，如
```
timeZone = 'Asia/Shanghai'
```
    timeZone = 'Asia/Shanghai'
    。
  - ```
  escape
```
  escape
  ：转义字符，默认值为
```
  \
```
  \
  。
- ```
nullValue
```
    nullValue
    ：判定 Null 的内容，默认值为
```
""
```
    ""
    。
  - ```
  multiLine
```
  multiLine
  ：是否有跨行的 csv 记录，默认值为
```
  false
```
  false
  。
- ```
writebom
```
    writebom
    ：是否写入 BOM 头，默认
```
false
```
    false
    。若导出 CSV 需在 Windows Excel 中打开，建议设为
```
true
```
    true
    。
  - ```
  headerQuotingStyle
```
  headerQuotingStyle
  ：默认
```
  needed
```
  needed
  ，可选
```
  none
```
  none
  。
- ```
dataQuotingStyle
```
    dataQuotingStyle
    ：默认
```
needed
```
    needed
    ，可选
```
none-unsafe
```
    none-unsafe
    。
-- 指定分隔符为 | 和压缩 COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = ( type= CSV sep='|' compression='gzip' );
- JSON 格式支持的参数：
  - ```
  compression
```
  compression
  ：源文件/目标文件是否压缩，默认不压缩。
COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = ( type= json );
- Parquet, ORC, BSON 格式：无额外参数。
COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = ( type= parquet );
copyOptions：
- ```
overwrite=true
```
  overwrite=true
  ：清空目标文件夹后导出（含子目录）。
- ```
filename_prefix = '<prefix_name>'
```
  filename_prefix = '<prefix_name>'
  ：设置文件前缀。
- ```
filename_suffix = '<suffix>'
```
  filename_suffix = '<suffix>'
  ：设置文件后缀。
- ```
include_job_id = 'TRUE' | 'FALSE'
```
  include_job_id = 'TRUE' | 'FALSE'
  ：文件名是否包含作业 ID。
- ```
single = true | false
```
  single = true | false
  ：是否导出为单个文件。默认
```
false
```
  false
  。
  -- 给文件添加前缀 COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type= json) filename_prefix='birds'; -- 导出为单文件 COPY INTO USER VOLUME SUBDIRECTORY 'export_single/' FROM TABLE birds file_format = (type = CSV) single = true;

返回结果说明

COPY INTO ... LOCATION

COPY INTO ... LOCATION

执行成功后不返回行数据。可通过

SHOW VOLUME DIRECTORY

SHOW VOLUME DIRECTORY

验证导出结果：

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

注意事项

默认文件名：Lakehouse 导出时，默认文件名是相同的。因此，如果你多次运行导出操作并且指定了相同的子目录（SUBDIRECTORY），新文件将覆盖上次导出的文件。
避免覆盖：为了防止意外覆盖现有文件，请确保每次导出时使用唯一的文件名或子目录，或使用
```
filename_prefix
```
filename_prefix
/
```
filename_suffix
```
filename_suffix
。

使用示例

导出数据到 User Volume

CREATE TABLE birds ( id INT, name VARCHAR(50), wingspan_cm FLOAT, colors STRING ); INSERT INTO birds (id, name, wingspan_cm, colors) VALUES (1, 'Sparrow', 15.5, 'Brown'), (2, 'Blue Jay', 20.2, 'Blue'), (3, 'Cardinal', 22.1, 'Red'), (4, 'Robin', 18.7, 'Red","Brown'); COPY INTO USER VOLUME SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV); -- 查看是否导出成功 SHOW USER VOLUME DIRECTORY SUBDIRECTORY 'dau_unload/'; -- 删除文件避免占用存储 REMOVE USER VOLUME FILE 'dau_unload/part00001.csv';

导出数据到 Table Volume

COPY INTO TABLE VOLUME birds SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV); -- 查看是否导出成功 SHOW TABLE VOLUME DIRECTORY birds SUBDIRECTORY 'dau_unload/'; -- 删除文件避免占用存储 REMOVE TABLE VOLUME birds FILE 'dau_unload/part00001.csv';

导出数据到外部 Volume (OSS/COS/S3)

导出到外部 Volume 的前提是已创建 VOLUME 和 CONNECTION。

-- 创建表 CREATE TABLE birds ( id INT, name VARCHAR(50), wingspan_cm FLOAT, colors STRING ); INSERT INTO birds (id, name, wingspan_cm, colors) VALUES (1, 'Sparrow', 15.5, 'Brown'), (2, 'Blue Jay', 20.2, 'Blue'), (3, 'Cardinal', 22.1, 'Red'), (4, 'Robin', 18.7, 'Red","Brown'); -- 创建 OSS Connection CREATE STORAGE CONNECTION catalog_storage_oss type OSS ACCESS_ID='xxxx' ACCESS_KEY='xxxxxxx' ENDPOINT='oss-cn-hangzhou-internal.aliyuncs.com'; -- 创建 External Volume CREATE EXTERNAL VOLUME my_volume location 'oss://mybucket/test_insert/' using connection catalog_storage_oss directory = (enable=true, auto_refresh=true); -- 将数据导出到子目录下 COPY INTO VOLUME my_volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV);

导出 EXCEL 兼容格式并下载到本地

-- 1. 导出到 User Volume（添加 BOM 头） COPY INTO user volume SUBDIRECTORY 'dau_unload/' FROM TABLE birds file_format = (type = CSV, writebom = true); -- 2. 下载到本地（需在 CLI 中执行，Studio 不支持 GET） SHOW USER VOLUME DIRECTORY; GET USER VOLUME FILE 'dau_unload/part00001.csv' TO '/tmp/'; -- 3. 清理 Volume 中的临时文件 REMOVE USER VOLUME FILE 'dau_unload/part00001.csv';