copy_file 函数

适用于:检查标记为“是”的 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_EXISTS
  • COPY_FILE_ERROR.FILE_ALREADY_EXISTS
  • COPY_FILE_AUTHORIZATION_ERROR.READ_UNAUTHORIZED
  • COPY_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