COPY INTO

適用於：勾選為「是」Databricks SQL 勾選為「是」Databricks Runtime

將數據從檔案位置載入 Delta 資料表。 這是一個可重試且冪立的操作。 已載入的來源位置檔案會被跳過。 即使檔案自載入後已修改，也是如此。 如需範例，請參閱 使用 COPY INTO的常見資料載入模式。

語法

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

參數

  • target_table

    識別現有的 Delta 數據表。 目標表不得包含時態規格或選項規格。

    如果數據表名稱是以位置的形式提供，例如： delta.`/path/to/table` ，Unity 目錄可以控管寫入位置的存取權。 您可以透過以下方式將資料寫入外部位置：

    • 將該位置定義為外部位置，並具有對該外部位置的WRITE FILES許可權。
    • 擁有在具名儲存認證上的 WRITE FILES 權限，提供授權以使用下列方式寫入位置： COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>)

    如需詳細資訊，請參閱 使用 Unity 目錄連線到雲端物件記憶體 。

  • BY POSITION |（col_name [ ， <col_name> ... ] ）

    按照序號位置比對源數據欄，對應至目標表的欄位。 相符數據行的類型轉換會自動完成。

    此參數僅支援無標頭 CSV 檔案格式。 您必須指定 FILEFORMAT = CSV。 FORMAT_OPTIONS 也必須設定為 ("headers" = "false") （FORMAT_OPTIONS ("headers" = "false") 是預設值）。

    語法選項 1： BY POSITION

    • 依序數位置自動比對源數據行與目標數據表數據行。
      • 預設的名稱比對不會被用來進行比對。
      • IDENTITY 列和目標表中的 GENERATED 列在比對源表的列時會被忽略。
      • 如果源數據行數目不等於篩選的目標數據表數據行， COPY INTO 則引發錯誤。

    語法選項 2： ( col_name [ , <col_name> ... ] )

    • 使用括弧中的目標數據表數據行名稱清單，依相對序數位置比對源數據行與指定的目標數據表數據行，並以逗號分隔。
      • 原始數據表數據行順序和數據行名稱不會用於比對。
      • IDENTITY 欄和 GENERATED 欄不能在欄名稱清單中指定，否則 COPY INTO 會引發錯誤。
      • 無法複製指定的數據列。
      • 當源數據行數目不等於指定的數據表數據行時， COPY INTO 引發錯誤。
      • 針對未在資料行名稱清單中指定的數據行， COPY INTO 如果有任何，則會指派預設值，否則指派 NULL 。 如果任何欄不允許為 Null，COPY INTO 就會引發錯誤。

  • source

    要從中載入資料的檔案位置。 此位置中的檔案必須具有 中指定的 FILEFORMAT格式。 位置是以 URI 的形式提供。

    您可以透過下列方式提供來源位置的存取權：

    • credential_name

      用來存取或寫入記憶體位置的認證選擇性名稱。 只有當檔案位置未包含在 外部位置時，您才會使用此認證。 請參閱 credential_name。

    • 內嵌暫存認證。

    • 將來源位置設定為外部位置，並透過 Unity Catalog 擁有對該外部位置的 READ FILES 許可權。
    • 使用具名的儲存憑證和具有READ FILES許可權，以透過 Unity 目錄授權從某個位置讀取。

    如果路徑已定義為您有權使用的外部位置，則不需要提供內嵌或具名認證。 如需詳細資訊，請參閱 外部位置概觀 。

    注意

    如果來源檔案路徑是根路徑，請在檔案路徑結尾新增斜線 （/），例如 s3://my-bucket/。

    接受的認證選項包括：

    • AZURE_SAS_TOKEN：ADLS 和 Azure Blob 儲存體
    • AWS_ACCESS_KEY、 AWS_SECRET_KEY、 和 AWS_SESSION_TOKEN for AWS S3

    接受的加密選項如下：

    • TYPE = 'AWS_SSE_C' 和 MASTER_KEY 適用於 AWS S3

請參閱 使用具有暫存認證的 COPY INTO 載入資料。

  • SELECT expression_list

    先從源數據選取指定的數據行或表達式，再複製到 Delta 數據表。 表示式可以是您搭配 SELECT 語句使用的任何內容，包括視窗操作。 您只能針對全域匯總使用匯總表達式，而無法在 GROUP BY 具有此語法的數據行上使用匯總表達式。

  • FILEFORMAT = data_source

    要載入的來源檔案格式。 在 CSV、JSON、AVRO、ORC、PARQUET、TEXT、BINARYFILE 中其中一個。

  • VALIDATE

    適用於：確認勾選「是」 Databricks SQL 確認勾選「是」 Databricks Runtime 10.4 LTS 及以上版本

    要載入數據表的數據會經過驗證，但不會寫入數據表。 這些驗證包括：

    • 是否可以剖析數據。
    • 架構是否與數據表的結構相符，或者需要修改架構。
    • 是否滿足所有可為 Null 的屬性和檢查約束條件。

    預設值是驗證要載入的所有數據。 您可以提供若干資料列，以ROWS關鍵字進行驗證，例如VALIDATE 15 ROWS。 語句 COPY INTO 當使用小於 50 的數字搭配 ROWS 關鍵詞時，會返回 50 行或更少的數據預覽。

  • FILES

    要載入的檔名清單，限制為1000個檔案。 無法與 PATTERN 一起指定。

  • PATTERN

    Glob 模式，識別要從來源目錄載入的檔案。 無法與 FILES 一起指定。

    圖案 描述
    ? 匹配任何單一字元
    * 比對零或多個字元
    [abc] 比對字元集 {a，b，c} 的單一字元。
    [a-z] 比對字元範圍 {a...z} 的單一字元。
    [^a] 匹配不屬於字元集或範圍 {a} 的單一字元。 請注意， ^ 字元必須緊接在左括弧右邊。
    {ab,cd} 比對字串集 {ab， cd} 中的字串。
    {ab,c{de, fh}} 比對字串集 {ab， cde， cfh} 中的字串。

  • FORMAT_OPTIONS

    要傳遞到指定格式的 Apache Spark 資料來源閱讀器的選項。 請參閱 每個檔案格式的格式選項 。

  • COPY_OPTIONS

    用於控制 COPY INTO 指令運行的選項。

    • force：布爾值，預設值 false。 如果設定為 true，則會停用等冪性，而且檔案會載入，而不論檔案之前是否已載入。
    • mergeSchema：布爾值，預設值 false。 如果設定為 true，則可以根據傳入數據來演進架構。

同時調用 COPY INTO

COPY INTO 支援對相同數據表的並行調用。 只要COPY INTO在不同的輸入檔案集合上同時執行，每次執行最終都會成功，否則您會遇到交易衝突。 COPY INTO 不應同時執行以提升效能；相比對每個單一檔案分別執行多個並行 COPY INTO 命令，單一個包含多個檔案的 COPY INTO 命令通常表現得更好。 COPY INTO 可以同時調用當：

  • 多個數據產生者沒有簡單的協調方式，而且無法進行單一調用。
  • 當必須逐個子目錄擷取非常大型的目錄時。 擷取具有大量檔案的目錄時，Databricks 建議盡可能使用 自動載入器 。

存取檔案元數據

若要瞭解如何存取檔案型數據源的元數據，請參閱 檔案元數據數據行。

格式選項

關於每種檔案格式（JSON、CSV、XML、Parquet、Avro、文字、ORC及二進位）的專屬選項，請參閱 DataFrameReader 選項。

  • 上次更新時間：