Lakehouse 文件批量导入导出指南（COPY INTO）
概述
COPY INTO
COPY INTO
是云器 Lakehouse 提供的高性能数据批量导入导出命令，支持从 Volume 批量加载 CSV、Parquet、ORC 等格式文件到表中，或将表数据导出为文件。本指南按业务场景分类，帮助你快速掌握高效的数据搬运方法。
快速导航：从 Volume 导入 CSV · 从 Volume 导入 Parquet · 导出表数据到 Volume · 处理导入错误 · 查看加载历史
涉及的 SQL 命令
| 命令 | 用途 | 适用场景 |
|---|
COPY INTO table FROM VOLUME ...
COPY INTO table FROM VOLUME ... | 从 Volume 导入文件 | 批量加载 CSV/Parquet/ORC |
COPY INTO USER VOLUME ... FROM table
COPY INTO USER VOLUME ... FROM table | 导出表数据到用户 Volume | 数据备份、外部系统交换 |
COPY INTO VOLUME name ... FROM table
COPY INTO VOLUME name ... FROM table | 导出表数据到外部 Volume | 导出到 OSS/COS/S3 |
load_history('table_name')
load_history('table_name') | 查看加载历史 | 审计导入记录和文件状态 |
前置准备
以下示例使用模拟的目标表
doc_copy_target
doc_copy_target
：
CREATE TABLE IF NOT EXISTS doc_copy_target (
id INT,
name STRING,
value DOUBLE
);
示例中使用名为
my_volume
my_volume
的 Volume。执行前请将
my_volume
my_volume
替换为实际存在的 Volume 名称，可通过
SHOW VOLUMES
SHOW VOLUMES
查看可用 Volume。
从 Volume 导入 CSV
使用
COPY INTO
COPY INTO
从 Volume 批量导入 CSV 文件。
COPY INTO doc_copy_target
FROM VOLUME my_volume
USING CSV
OPTIONS ('header' = 'true');
指定文件名导入：
COPY INTO doc_copy_target
FROM VOLUME my_volume
USING CSV
OPTIONS ('header' = 'true', 'sep' = ',')
FILES('data.csv');
常用 OPTIONS 参数：
header = 'true'
header = 'true'
：跳过第一行表头sep = ','
sep = ','
：指定列分隔符（默认逗号）quote = '"'
quote = '"'
：指定引号字符
💡 提示：
COPY INTO
COPY INTO
会自动跳过已导入的文件（基于文件路径记录），支持增量加载，重复执行不会重复导入相同文件。
从 Volume 导入 Parquet
Parquet 是列式存储格式，导入性能通常优于 CSV。
COPY INTO doc_copy_target
FROM VOLUME my_volume
FILES('data.parquet')
USING PARQUET;
优势：
- 自动推断 Schema，无需手动定义列映射
- 压缩率高，网络传输和解析更快
导出表数据到 Volume
导出到用户 Volume（User Volume）：
COPY INTO USER VOLUME
SUBDIRECTORY 'export/doc_copy_target/'
FROM doc_copy_target
FILE_FORMAT = (TYPE = CSV);
导出到外部 Volume（需提前创建 External Volume）：
COPY INTO VOLUME my_volume
SUBDIRECTORY 'export/'
FROM doc_copy_target
FILE_FORMAT = (TYPE = PARQUET);
适用场景：
- 数据备份到对象存储
- 向下游系统提供数据文件
- 机器学习特征导出
处理导入错误
使用
ON_ERROR
ON_ERROR
参数控制遇到格式错误时的处理策略。
-- 跳过错误行并继续导入
COPY INTO doc_copy_target
FROM VOLUME my_volume
USING CSV
OPTIONS ('header' = 'true')
FILES('data.csv')
ON_ERROR = 'CONTINUE';
可选策略：
CONTINUE
CONTINUE
：跳过错误行，继续导入剩余数据；适合容忍部分错误、要求最大限度完成加载的场景ABORT
ABORT
：遇到错误立即终止整个导入操作；适合严格数据质量要求、任何错误都需人工介入的场景
指定
ON_ERROR
ON_ERROR
后，命令返回每个文件的导入结果，包含以下列：
| 列名 | 说明 |
|---|
file
file | 导入的文件完整路径 |
status
status | 导入状态：SUCCESS
SUCCESS 或 LOADED_FAILED
LOADED_FAILED |
rows_loaded
rows_loaded | 成功导入的行数 |
first_error
first_error | 第一条错误信息（成功时为空） |
查看加载历史
使用
load_history
load_history
函数查看表的文件导入记录。
SELECT * FROM load_history('doc_copy_target');
返回列说明：
| 列名 | 说明 |
|---|
file_path
file_path | 导入的文件路径 |
last_copy_time
last_copy_time | 最近一次导入时间 |
file_size
file_size | 文件大小（字节） |
status
status | 导入状态 |
first_error_message
first_error_message | 第一条错误信息 |
清理测试数据
DROP TABLE IF EXISTS doc_copy_target;
💡 提示：Lakehouse 支持
UNDROP TABLE
UNDROP TABLE
，误删后可在保留期内恢复。
注意事项
- 幂等性：
COPY INTO
COPY INTO
记录已导入文件路径，重复执行不会重复加载相同文件。如需强制重新导入，使用 COPY OVERWRITE INTO
COPY OVERWRITE INTO
。
- Schema 匹配：导入时文件列顺序需与表定义一致，或使用
MATCH_BY_COLUMN_NAME = 'CASE_SENSITIVE'
MATCH_BY_COLUMN_NAME = 'CASE_SENSITIVE'
按列名匹配。
- 大文件拆分：建议将超大文件拆分为多个小文件（100MB–1GB），提升并行导入性能。
- 权限要求：执行
COPY INTO
COPY INTO
需要对目标表具有 INSERT
INSERT
权限，对 Volume 具有 READ
READ
权限。
- 导出路径：导出到已存在路径时默认追加文件，不覆盖已有文件。如需覆盖，使用
COPY OVERWRITE INTO
COPY OVERWRITE INTO
。
相关文档
