適用於:
Databricks SQL
執行時間 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_filefunction。
常見錯誤條件
COPY_FILE_ERROR.FILE_NOT_EXISTSCOPY_FILE_ERROR.FILE_ALREADY_EXISTSCOPY_FILE_AUTHORIZATION_ERROR.READ_UNAUTHORIZEDCOPY_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