適用於:
Databricks SQL
執行時間 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_EXISTSCOPY_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'
);