try_copy_file 函数

适用于:检查标记为“是”的 Databricks SQL 检查标记为“是”是 Databricks Runtime 18 LTS 及更高版本

Important

此功能在 Beta 版中。

将文件复制到目标路径并返回 FILE 引用,或者 NULL 当源文件不存在或无法访问时返回。 省略 destination 将文件复制到 Unity Catalog 管理的存储,该存储将 FILE EXTERNAL 引用转换为引用 FILE MANAGED 。

Syntax

try_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 引用复制文件的值,或者 NULL 如果源文件不存在或无法访问。

备注

  • 该函数是函数的容错版本copy_file。 在将 FILE EXTERNAL 引用转换为引用 FILE MANAGED 时,无论转换是显式(省 destination略)还是自动(在列中插入 FILE EXTERNAL 值 FILE MANAGED )时,都可以用它忽略错误。
  • 如果目标路径已经存在文件,Azure Databricks 默认会报错,除非你设置为 if_file_exists_modeoverwrite 或 skip。

常见错误条件

  • COPY_FILE_ERROR.FILE_ALREADY_EXISTS
  • COPY_FILE_AUTHORIZATION_ERROR.WRITE_UNAUTHORIZED

欲了解更多信息,请参见 Azure Databricks 中的错误条件。

Examples

如果源文件不存在,返回 try_copy_fileNULL:

SELECT try_copy_file(deleted_file, destination => '/Volumes/archive/reports/report.pdf');
NULL

要将文件复制到 Unity Catalog 管理的存储,将引用转换为 FILE EXTERNAL 引用 FILE MANAGED ,请省略目标:

SELECT try_copy_file(to_file('/Volumes/source/data/input.csv'));

要复制文件并覆盖任何已有的目标文件:

SELECT try_copy_file(
  to_file('/Volumes/source/reports/report.pdf'),
  destination => '/Volumes/archive/reports/report.pdf',
  if_file_exists_mode => 'overwrite'
);