copy_file 函數

適用於：勾選標記為是 Databricks SQL 勾選 Databricks 執行時間 18 LTS 及以上

Important

這項功能位於 測試版 (Beta) 中。 工作區管理員可以從 「預覽 」頁面控制對此功能的存取。 請參閱 管理 Azure Databricks 預覽。

將檔案複製到目的地路徑，並回傳 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
  • Last updated on