copy_file 函數

適用於:勾選標記為是 Databricks SQL 勾選 Databricks 執行時間 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 目錄管理的儲存空間,將參考資料轉換 FILE EXTERNAL 成參考 FILE MANAGED 資料。
  • if_file_exists_mode:一個可選 STRING 的選項,當目標路徑已有檔案時,設定行為。 只適用於使用該 destination 論證時。 接受的值(大小寫不區分)包括:
    • 'error':會產生錯誤。 這是預設值。
    • 'overwrite': 覆蓋現有檔案。
    • 'skip'跳過複製,回傳 FILE 對現有檔案的參考。

Returns

一個 FILE 參考複製檔案的值。

Notes

  • 省略 destination 則將 FILE EXTERNAL 參考 FILE MANAGED轉換為 。 Azure Databricks 也會在你將值插入FILE EXTERNALFILE MANAGED欄位時自動套用這個轉換。
  • 如果目標路徑已經有檔案存在,Azure Databricks 預設會報錯,除非你設定if_file_exists_mode為 overwrite 或 skip。
  • 如果來源檔案不存在,Azure Databricks 會產生錯誤。 若要返回 NULL 而非在任何情況下產生錯誤,請使用 try_copy_file function。

常見錯誤條件

  • 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