try_copy_file 函數

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

Returns

一個 FILE 參考複製檔案的值,或 NULL 是如果原始檔案不存在或無法存取。

Notes

  • 這個函數是函數的容錯版本copy_file。 利用它來忽略將參考轉換 FILE EXTERNAL 到參考 FILE MANAGED 時的錯誤,無論是顯式(省 destination略)或自動(在欄位插入 FILE EXTERNAL 值 FILE MANAGED )都一樣。
  • 如果目標路徑已經有檔案存在,Azure Databricks 預設會報錯,除非你設定if_file_exists_mode為 overwrite 或 skip。

常見錯誤條件

  • COPY_FILE_ERROR.FILE_ALREADY_EXISTS
  • COPY_FILE_AUTHORIZATION_ERROR.WRITE_UNAUTHORIZED

欲了解更多資訊,請參閱 Azure Databricks 中的錯誤條件。

Examples

若來源檔案不存在,則 try_copy_file 回傳 NULL:

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

若要將檔案複製到 Unity 目錄管理的儲存空間,將參考轉換 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'
);