适用于:
Databricks SQL
Databricks Runtime 18 LTS 及更高版本
Important
此功能在 Beta 版中。
将文件复制到目标路径,并返回 FILE 对复制文件的引用。 省略 destination 将文件复制到 Unity Catalog 管理的存储,该存储将 FILE EXTERNAL 引用转换为引用 FILE MANAGED 。
Syntax
copy_file(file => file
[, destination => destination ]
[, if_file_exists_mode => mode ])
你可以按位置或名字传递论点。 在你通过名称传递参数后,后续所有参数也必须按名称传递。 更多信息请参见 命名参数调用。
Arguments
-
file:一个FILE需要复制的值。 -
destination:一个STRING可选的,包含完整的目标文件路径,而不仅仅是一个目录。 当被省略时,文件会被复制到Unity Catalog管理的存储中,将FILE EXTERNAL引用转换为引用FILE MANAGED。 -
if_file_exists_mode:一个可选STRING程序,在目标路径已有文件时设置行为。 仅适用于使用该destination论证时。 公认值(大小写不区分)有:-
'error':出现错误。 这是默认值。 -
'overwrite': 覆盖现有文件。 -
'skip'跳过复制,返回FILE对现有文件的引用。
-
Returns
一个 FILE 引用复制文件的值。
备注
- 省略
destination则将FILE EXTERNAL引用FILE MANAGED转换为 。 Azure Databricks 在你将值插入FILE EXTERNALFILE MANAGED列时也会自动应用这种转换。 - 如果目标路径已经存在文件,Azure Databricks 默认会报错,除非你设置为
if_file_exists_modeoverwrite或skip。 - 如果源文件不存在,Azure Databricks 会报错。 无论哪种情况,要返回
NULL而非引发错误,请使用try_copy_file函数。
常见错误条件
COPY_FILE_ERROR.FILE_NOT_EXISTSCOPY_FILE_ERROR.FILE_ALREADY_EXISTSCOPY_FILE_AUTHORIZATION_ERROR.READ_UNAUTHORIZEDCOPY_FILE_AUTHORIZATION_ERROR.WRITE_UNAUTHORIZED
欲了解更多信息,请参见 Azure Databricks 中的错误条件。
Examples
要将文件从一个卷复制到另一个卷:
SELECT copy_file(
to_file('/Volumes/source/data/input.csv'),
destination => '/Volumes/target/data/output.csv'
);
使用每行文件名将文件复制到目标卷:
SELECT copy_file(
source_file,
destination => '/Volumes/my_catalog/my_schema/my_volume/processed/' || file_name,
if_file_exists_mode => 'skip'
)
FROM staging_files;
如果已有文件,要覆盖目标:
SELECT copy_file(
to_file('/Volumes/source/reports/report.pdf'),
destination => '/Volumes/archive/reports/report.pdf',
if_file_exists_mode => 'overwrite'
);
如果源文件不存在, copy_file 则会引发错误:
SELECT copy_file(deleted_file, destination => '/Volumes/archive/reports/report.pdf');
Error: COPY_FILE_ERROR.FILE_NOT_EXISTS