共用方式為


COPY INTO (Transact-SQL)

適用於:Azure Synapse Analytics

本文說明如何在 Azure Synapse Analytics 中使用 COPY 陳述式,以從外部儲存體帳戶載入。 COPY 陳述式提供最大的彈性,可將高輸送量資料擷取到 Azure Synapse Analytics 中。

注意

如需 Microsoft Fabric 中的倉儲,請流覽 COPY INTO

將 COPY 用於下列功能:

  • 使用具有較低權限的使用者來載入,而不需要對資料倉儲設定嚴格的 CONTROL 權限
  • 執行單一 T-SQL 語句,而不需要建立任何其他資料庫物件
  • 正確剖析和載入 CSV 檔案,其中分隔符(字串、欄位、數據列)會在字串分隔數據行內
  • 在不使用共用存取簽章 (SAS) 公開儲存體帳戶金鑰的情況下,指定更精細的權限模型
  • 針對 ERRORFILE 位置 (REJECTED_ROW_LOCATION) 使用不同的儲存體帳戶
  • 自訂每個目標資料行的預設值,並指定要載入特定目標資料行的來源資料欄位
  • 指定 CSV 檔案的自訂資料列終止符、欄位終止符和欄位引號
  • 針對 CSV 檔案使用 SQL Server 日期格式
  • 在儲存體位置路徑中指定萬用字元和多個檔案
  • 自動結構描述探索會簡化定義來源資料並將其對應至目標資料表的程序
  • 自動建立資料表程序會自動建立資料表,並與自動結構描述探索搭配運作
  • 從 Parquet 檔案直接載入複雜的數據類型,例如地圖和清單到字串數據行,而不需使用其他工具來預先處理數據

注意

若要從 Parquet 檔案載入複雜的數據類型,必須使用 來開啟 AUTO_CREATE_TABLE自動建立數據表。

請瀏覽下列文件,以取得使用 COPY 陳述式的完整範例和快速入門:

注意

Microsoft Entra ID 先前稱為 Azure Active Directory (Azure AD)。

語法

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

引數

schema_name

如果執行作業之使用者的預設架構是指定數據表的架構,則為選擇性。 如果未 指定架構 ,且執行 COPY 作業之使用者的預設架構與指定數據表的架構不同,則會取消 COPY,並傳回錯誤訊息。

table_name

要複製到其中之數據表的名稱。 目標資料表可以是臨時或永久資料表,而且必須已經存在於資料庫中。 針對自動架構偵測模式,請勿提供數據行清單。

(column_list)

一或多個數據行的選擇性清單,用來將源數據欄位對應至目標數據表數據行以載入資料。

請勿在 AUTO_CREATE_TABLE = 'ON'指定column_list

column_list 必須以括弧括住,並以逗號分隔。 資料行清單採用以下格式:

[(Column_name [default Default_value] [Field_number] [,...n])]

  • Column_name - 目標資料表中資料行的名稱。
  • Default_value - 預設值,取代輸入檔中的任何 NULL 值。 預設值適用於所有檔案格式。 當從數據行清單省略數據行或有空白輸入檔欄位時,COPY 會嘗試從輸入檔載入NULL。 預設值在關鍵詞 『default』 之前
  • Field_number - 對應至目標數據行的輸入檔欄位編號。
  • 欄位索引會從 1 開始。

未指定數據行清單時,COPY 會根據來源和目標順序對應數據行:輸入欄位 1 會移至目標資料行 1、字位 2 會移至資料行 2 等等。

外部位置

這是包含資料的檔案暫存之處。 目前支援 Azure Data Lake Storage (ADLS) Gen2 和 Azure Blob 儲存體:

  • Blob 儲存體的「外部位置」:https://<account\>.blob.core.windows.net/<container\>/<path\>
  • ADLS Gen2 的「外部位置」:https://<account\>.dfs.core.windows.net/<container\>/<path\>

注意

Blob 端點也適用於 ADLS Gen2,且目前能夠執行最佳效能。 當驗證方法不需要 .dfs 時,請使用 .blob 端點。

  • 帳戶 - 儲存體帳戶名稱

  • 容器 - Blob 容器名稱

  • 路徑 - 資料的資料夾或檔案路徑。 位置會從容器開始。 如果指定資料夾,COPY 會從資料夾及其所有子資料夾擷取所有檔案。 COPY 會忽略隱藏的資料夾,而且不會傳回以底線 () 或句號 (_.) 開頭的檔案,除非在路徑中明確指定。 即使在使用萬用字元指定路徑時,此行為也是相同的。

萬用字元可以包含在路徑中,其中

  • 萬用字元路徑名稱比對會區分大小寫
  • 通配符可以使用反斜杠字元逸出 (\
  • 萬用字元展開會以遞迴方式套用。 例如,下列範例會載入 Customer1 下的所有 CSV 檔案(包括 Customer1 的子目錄): Account/Container/Customer1/*.csv

注意

為獲得最佳效能,請避免指定會擴展到大量檔案的萬用字元。 如果可能,請列出多個檔案位置,而不是指定萬用字元。

您只能透過逗號分隔清單,從相同的儲存體帳戶和容器中指定多個檔案位置,例如:

  • https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' }

FILE_TYPE 會指定外部資料的格式。

  • CSV:指定符合 RFC 4180 標準的逗號分隔值檔案。
  • PARQUET:指定 Parquet 格式。
  • ORC:指定 Optimized Row Columnar (ORC) 格式。

注意

PolyBase 中的檔案類型「分隔符號文字」已由 'CSV' 檔案格式所取代,其中預設的逗號分隔符號可以透過 FIELDTERMINATOR 參數設定。

FILE_FORMAT = external_file_format_name

FILE_FORMAT 僅適用於 Parquet 和 ORC 檔案,而且會指定儲存外部資料檔案類型和壓縮方法的外部檔案格式物件名稱。 若要建立外部檔案格式,請使用 CREATE EXTERNAL FILE FORMAT

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL 會指定存取外部儲存體帳戶的驗證機制。 驗證方法為:

CSV Parquet ORC
Azure Blob 儲存體 SAS/MSI/SERVICE PRINCIPAL/KEY/AAD SAS/KEY SAS/KEY
Azure Data Lake Gen2 SAS/MSI/SERVICE PRINCIPAL/KEY/AAD SAS (Blob 1 )/MSI (dfs 2 )/服務主體/金鑰/AAD SAS (Blob 1 )/MSI (dfs 2 )/服務主體/金鑰/AAD

1:此驗證方法需要外部位置路徑中的 .blob 端點 ( .blob.core.windows.net)。

2:此驗證方法需要外部位置路徑中的 .dfs 端點 ( .dfs.core.windows.net)。

注意

  • 使用 Microsoft Entra ID 或公用記憶體帳戶進行驗證時,不需要指定 CREDENTIAL。
  • 如果您的記憶體帳戶與 VNet 相關聯,您必須使用受控識別進行驗證。
  • 使用共用存取簽章 (SAS) 進行驗證

    • IDENTITY:值為「共用存取簽章」的常數
    • SECRET:共用存取簽章會提供記憶體帳戶中資源的委派存取權。
    • 所需最小權限:READ 和 LIST
  • 使用服務主體進行驗證

    • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
    • SECRET:Microsoft Entra 應用程式服務主體密鑰
    • 所需的最小 RBAC 角色:儲存體 Blob 資料參與者、儲存體 Blob 資料參與者、儲存體 Blob 資料擁有者或儲存體 Blob 資料讀者
  • 使用儲存體帳戶金鑰進行驗證

    • IDENTITY:值為「儲存體帳戶金鑰」的常數
    • SECRET:儲存體帳戶金鑰
  • 使用受控識別 (VNet 服務端點) 進行驗證

    • IDENTITY:值為「受控識別」的常數
    • 所需的最小 RBAC 角色:Azure 中Microsoft Entra 註冊邏輯伺服器的記憶體 Blob 數據參與者或記憶體 Blob 數據擁有者。 使用未與 Synapse Workspace 相關聯的專用 SQL 集區時,不需要此 RBAC 角色,但受控識別需要目標物件的 存取控制 清單 (ACL) 許可權,才能啟用來源檔案的讀取許可權
  • 使用 Microsoft Entra 使用者進行驗證

    • 不需要 CREDENTIAL
    • 所需的最小 RBAC 角色:Microsoft Entra 使用者的記憶體 Blob 數據參與者或記憶體 Blob 數據擁有者

ERRORFILE = 目錄位置

ERRORFILE 僅適用於 CSV。 指定 COPY 陳述式內,已拒絕資料列和相應錯誤檔案應寫入的目錄。 您可以指定儲存體帳戶的完整路徑,或指定相對於容器的路徑。 如果指定的路徑不存在,則會代表您建立一個路徑。 系統會建立名稱為 "_rejectedrows" 的子目錄。 "_" 字元可確保該目錄從其他資料處理逸出,除非已明確在位置參數中指名。

注意

當相對路徑傳遞至 ERRORFILE 時,路徑會相對於external_location中指定的容器路徑。

在此目錄中,會有一個根據載入提交時間建立的資料夾,格式為 YearMonthDay -HourMinuteSecond (例如 20180330-173205)。 在此資料夾中,會寫入兩種類型的檔案、原因 (Error) 檔案和數據 (Row) 檔案,每個檔案都會使用 queryID、distributionID 和檔案 guid 預先套用。 因為資料與原因檔案在不同的檔案中,所以對應的檔案會具有相符首碼。

如果 ERRORFILE 已定義記憶體帳戶的完整路徑,則會使用ERRORFILE_CREDENTIAL來連線到該記憶體。 否則會使用 CREDENTIAL 所述的值。 當源數據所使用的相同認證用於 ERRORFILE 時,套用至ERRORFILE_CREDENTIAL的限制也會套用

ERRORFILE_CREDENTIAL = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL 僅適用於 CSV 檔案。 支援的資料來源和驗證方法為:

  • Azure Blob 儲存體 - SAS/SERVICE PRINCIPAL/AAD

  • Azure Data Lake Gen2 - SAS/MSI/SERVICE PRINCIPAL/AAD

  • 使用共用存取簽章 (SAS) 進行驗證

    • IDENTITY:值為「共用存取簽章」的常數
    • SECRET:共用存取簽章會提供記憶體帳戶中資源的委派存取權。
    • 所需最小權限:READ、LIST、WRITE、CREATE、DELETE
  • 使用服務主體進行驗證

    • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
    • SECRET:Microsoft Entra 應用程式服務主體密鑰
    • 所需的最小 RBAC 角色:儲存體 Blob 資料參與者或儲存體 Blob 資料擁有者

注意

使用 OAuth 2.0 權杖端點 V1

  • 使用受控識別 (VNet 服務端點) 進行驗證

    • IDENTITY:值為「受控識別」的常數
    • 所需的最小 RBAC 角色:Microsoft Entra 已註冊 SQL 資料庫 伺服器的記憶體 Blob 數據參與者或記憶體 Blob 數據擁有者
  • 使用 Microsoft Entra 使用者進行驗證

    • 不需要 CREDENTIAL
    • 所需的最小 RBAC 角色:Microsoft Entra 使用者的記憶體 Blob 數據參與者或記憶體 Blob 數據擁有者

不支援使用記憶體帳戶密鑰搭配ERRORFILE_CREDENTIAL。

注意

如果您要將相同的儲存體帳戶用於 ERRORFILE,並指定相對於容器根目錄的 ERRORFILE 路徑,則不需要指定 ERROR_CREDENTIAL。

MAXERRORS = max_errors

MAXERRORS 指定 COPY 作業失敗之前,載入中允許的拒絕數據列數目上限。 COPY 作業無法匯入的每個數據列都會被忽略,並計算為一個錯誤。 如果未指定max_errors,則預設值為 0。

MAXERRORS 無法與AUTO_CREATE_TABLE搭配使用。

FILE_TYPE 為 『PARQUET』時,數據類型轉換錯誤所造成的例外狀況(例如 Parquet 二進位檔為 SQL 整數)仍然會導致 COPY INTO 失敗,忽略 MAXERRORS

COMPRESSION = { 'DefaultCodec ' |'Snappy' |'GZIP' |'NONE'}

COMPRESSION 是選用的,而且會指定外部資料的資料壓縮方法。

  • CSV 支援 GZIP
  • Parquet 支援 GZIP 和 Snappy
  • ORC 支援 DefaultCodec 和 Snappy。
  • Zlib 是 ORC 的預設壓縮

COPY 命令會在未指定此參數時,根據擴展名自動偵測壓縮類型:

  • .gz - GZIP
  • .snappy – Snappy
  • .deflate - DefaultCodec (僅限 Parquet 和 ORC)

COPY 命令要求 gzip 檔案不包含任何尾端垃圾才能正常運作。 gzip 格式嚴格要求檔案由有效的成員組成,而不需要在檔案之前、之間或之後提供任何其他資訊。 此格式的任何偏差,例如尾端非 gzip 資料的存在,都會導致 COPY 命令失敗。 請務必確認 gzip 檔案結尾沒有尾端垃圾,以確保 COPY 可以成功處理這些檔案。

FIELDQUOTE = 'field_quote'

FIELDQUOTE 適用於 CSV,並指定在 CSV 檔案中做為引號字元(字串分隔符)的單一字元。 如果未指定,則會使用引號字元 (“) 作為 RFC 4180 標準中所定義的引號字元。 FIELDQUOTE 也支援十六進位表示法。 FIELDQUOTE 的UTF-8不支援擴充 ASCII 和多位元組字元。

注意

FIELDQUOTE 字元會在有雙 FIELDQUOTE (分隔符號) 存在的字串資料行中逸出。

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR 僅適用於 CSV。 指定 CSV 檔案中使用的欄位終止符。 您可以使用十六進位標記法來指定欄位結束字元。 欄位結束字元可以是多個字元。 預設的欄位結束字元為 (,)。 FIELDTERMINATOR 的 UTF-8 不支援擴充 ASCII 和多位元組字元。

ROW TERMINATOR = 'row_terminator'

ROW TERMINATOR 僅適用於 CSV。 指定 CSV 檔案中使用的數據列終止符。 您可以使用十六進位標記法來指定資料列結束字元。 資料列結束字元可以是多個字元。 根據預設,資料列終止符為 \r\n

COPY 命令 \r 會在指定 \n 時前置字元(換行符),以產生 \r\n。 若要只 \n 指定字元,請使用十六進位表示法 (0x0A)。 在十六進位中指定多字元數據列終止符時,請勿在每個字元之間指定 0x。

數據列終止符的UTF-8不支援擴充 ASCII 和多位元組字元。

FIRSTROW = First_row_int

FIRSTROW 會套用至 CSV,並指定在 COPY 命令的所有檔案中第一次讀取的資料列編號。 值會從 1 開始,也就是預設值。 如果將值設定為二,則在載入資料時,會略過每個檔案中的第一個資料列 (標題列)。 如果資料列存在資料列結束字元,就會略過。

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | 'dym' }

DATEFORMAT 僅適用於 CSV,而且會指定對應至 SQL Server 日期格式之日期的日期格式。 如需所有 Transact-SQL 日期和時間資料類型與函式的概觀,請參閱日期和時間資料類型與函式 (Transact-SQL)。 COPY 命令內的 DATEFORMAT 優先於在工作階段層級設定的 DATEFORMAT

ENCODING = 'UTF8' | 'UTF16'

ENCODING 僅適用於 CSV。 預設值為 UTF8。 指定 COPY 命令所載入之檔案的資料編碼標準。

IDENTITY_INSERT = 'ON' | 'OFF'

IDENTITY_INSERT 會指定所匯入資料檔案中的一或多個識別值是否要用於識別資料行。 如果 IDENTITY_INSERT 為 OFF (預設值),則會驗證這個資料行的識別值,但不會匯入。 Azure Synapse Analytics 會根據數據表建立期間指定的種子和增量值,自動指派唯一值。 請注意 COPY 命令的下列行為:

  • 如果IDENTITY_INSERT為 OFF,且數據表具有識別數據行
    • 必須指定數據行清單,這不會將輸入字段對應至標識列。
  • 如果IDENTITY_INSERT為 ON,且數據表具有識別數據行
    • 如果傳遞資料行清單,則必須將輸入欄位對應到識別資料行。
  • 數據行清單中的 IDENTITY COLUMN 不支援預設值。
  • 一次只能為一個資料表設定 IDENTITY_INSERT。

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE 指定是否可以與自動結構描述探索搭配運作來自動建立資料表。 它僅適用於 Parquet 檔案。

  • ON:啟用自動建立資料表。 COPY INTO 程式會探索要載入的檔案結構,自動建立新的資料表。 也可以與預先存在的數據表搭配使用,以利用 Parquet 檔案的自動架構探索。
  • OFF:未啟用自動建立數據表。 預設值。

注意

自動建立資料表會與自動結構描述探索搭配運作。 預設「不會」啟用自動建立資料表。

請勿使用 COPY INTO 搭配 AUTO_CREATE_TABLE = 'ON' 從 Parquet 檔案載入哈希分散式數據表。

如果要使用 COPY INTO 將 Parquet 檔案載入哈希分散式數據表,請將它載入迴圈配置資源臨時表,後面接著 INSERT ...從該數據表選取目標哈希分散式數據表。

權限

執行 COPY 命令的使用者必須具有下列權限:

需要 INSERT 和 ADMINISTER BULK OPERATIONS 權限。 在 Azure Synapse Analytics 中,需要 INSERT 和 ADMINISTER DATABASE BULK OPERATIONS 權限。

此外,如果執行 COPY 命令的使用者也想要產生新的資料表並將數據載入其中,則需要 CREATE TABLE 和 ALTER ON SCHEMA 許可權。

例如,若要允許 mike@contoso.com 使用 COPY 在架構中 HR 建立新的數據表,並從 Parquet 檔案插入數據,請使用下列 Transact-SQL 範例:

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GRANT INSERT to [mike@contoso.com];

GRANT CREATE TABLE to [mike@contoso.com];
GRANT ALTER on SCHEMA::HR to [mike@contoso.com];

備註

COPY 語句只接受數據列數據和命令參數的 UTF-8 和 UTF-16 有效字元。 使用無效字元的原始程式檔或參數(例如 ROW TERMINATOR 或 FIELD TERMINATOR)可能會被 COPY 語句錯誤解譯,並導致數據損毀或其他失敗等非預期的結果。 在叫用 COPY 語句之前,請確定您的來源檔案和參數符合 UTF-8 或 UTF-16 規範。

範例

A. 從公用儲存體帳戶載入

下列範例是 COPY 命令的最簡單形式,它會從公用儲存體帳戶載入資料。 在此範例中,COPY 陳述式的預設值符合行項目 csv 檔案的格式。

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'
WITH (FIELDTERMINATOR = '|')

COPY 命令的預設值為:

  • DATEFORMAT = 工作階段 DATEFORMAT

  • MAXERRORS = 0

  • COMPRESSION 預設值為未壓縮

  • FIELDQUOTE = '“'

  • FIELDTERMINATOR = ','

  • ROWTERMINATOR = '\n'

重要

COPY 會在 \n 內部視為 \r\n 。 如需詳細資訊,請參閱 ROWTERMINATOR 一節。

  • FIRSTROW = 1

  • ENCODING = 'UTF8'

  • FILE_TYPE = 'CSV'

  • IDENTITY_INSERT = 'OFF'

B. 透過共用存取簽章 (SAS) 載入驗證

下列範例會載入使用換行字元作為資料列結束字元的檔案,如 UNIX 輸出。 此範例也會使用 SAS 金鑰向 Azure Blob 儲存體進行驗證。

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=';',
    ROWTERMINATOR='0X0A',
    ENCODING = 'UTF8',
    DATEFORMAT = 'ymd',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder',--path starting from the storage container
    IDENTITY_INSERT = 'ON'
)

C. 以具有預設值的資料行清單載入,並透過儲存體帳戶金鑰進行驗證

此範例會載入使用預設值指定資料行清單的檔案。

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_Account_Key>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. 使用現有的檔案格式物件載入 Parquet 或 ORC

此範例會使用通配符來載入資料夾下的所有 Parquet 檔案。

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_FORMAT = myFileFormat,
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
)

E. 透過指定萬用字元和多個檔案來載入

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= '<client_id>@<OAuth_2.0_Token_EndPoint>',SECRET='<key>'),
    FIELDTERMINATOR = '|'
)

F. 使用 MSI 認證載入

COPY INTO dbo.myCOPYDemoTable
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL = (IDENTITY = 'Managed Identity'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=','
)

G. 使用自動結構描述偵測載入

COPY INTO [myCOPYDemoTable]
FROM 'https://myaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.parquet'
WITH (
    FILE_TYPE = 'Parquet',
    CREDENTIAL = ( IDENTITY = 'Shared Access Signature',  SECRET='<key>'),
    AUTO_CREATE_TABLE = 'ON'
)

常見問題集

相較於 PolyBase,COPY 命令的效能為何?

COPY 命令根據您的工作負載有較佳的效能。

  • 壓縮檔案無法自動分割。 為了獲得最佳載入效能,請考慮在載入壓縮的 CSV 時,將您的輸入分割成多個檔案。

  • 大型未壓縮的 CSV 檔案可以自動分割和載入,因此在大部分情況下,不需要手動分割未壓縮的 CSV 檔案。 在某些情況下,由於數據特性而無法進行自動檔案分割,手動分割大型 CSV 仍可提升效能。

COPY 命令載入壓縮 CSV 檔案的檔案分割指導方針為何?

下表概述檔案數目的指引。 達到建議的檔案數目之後,您的效能就愈大。 檔案數目是由計算節點數目乘以 60 來決定。 例如,在 6000 個 DWU 中,我們有 12 個計算節點和 12*60 = 720 個分割區。 如需簡單的檔案分割體驗,請參閱如何使用檔案分割將 COPY 載入輸送量提到最高 (英文)。

DWU #Files
100 60
200 60
300 60
400 60
500 60
1,000 120
1,500 180
2,000 240
2,500 300
3,000 360
5,000 600
6,000 720
7,500 900
10,000 1200
15,000 1800
30,000 3600

COPY 命令載入 Parquet 或 ORC 檔案的檔案分割指導方針為何?

因為 COPY 命令會自動分割檔案,因此不需要分割 Parquet 和 ORC 檔案。 Azure 儲存體帳戶中的 Parquet 和 ORC 檔案應為 256 MB (含) 以上,才能獲得最佳效能。

檔案的數目或大小是否有任何限制?

檔案的數目或大小沒有限制,但為了獲得最佳效能,我們建議檔案至少為 4 MB。

COPY 陳述式是否有任何已知問題?

如果您有在 2020 年 12 月 7 日之前建立的 Azure Synapse 工作區,在使用受控識別進行驗證時,可能會遇到類似的錯誤訊息: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

請依照下列步驟,重新註冊工作區的受控識別來解決此問題:

  1. 安裝 Azure PowerShell。 請參閱安裝 PowerShell
  2. 使用 PowerShell 註冊工作區的受控識別:
    Connect-AzAccount
    Select-AzSubscription -SubscriptionId <subscriptionId>
    Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity
    

適用於:Microsoft Fabric 中的倉儲

本文說明如何在 Microsoft Fabric 中使用 Warehouse 中的 COPY 語句,從外部記憶體帳戶載入。 COPY 語句提供將高輸送量數據擷取到倉儲的最大彈性,而且是將數據內嵌到倉儲的策略

在 Microsoft Fabric 中 ,COPY (Transact-SQL) 語句目前支援 PARQUET 和 CSV 檔格式。 針對數據源,僅支援 Azure Data Lake Storage Gen2 帳戶。

如需在 Microsoft Fabric 中使用 WAREHOUSE INTO 的詳細資訊,請參閱 使用 COPY 語句將數據內嵌至您的倉儲。

根據預設, COPY INTO 會以執行中的 Entra ID 使用者身分進行驗證。

注意

針對 Azure Synapse Analytics,請流覽 COPY INTO for Azure Synapse Analytics

將 COPY 用於下列功能:

  • 使用較低許可權的使用者載入,而不需要對數據倉儲具有嚴格的CONTROL許可權。
  • 執行單一 T-SQL 語句,而不需要建立任何其他資料庫物件。
  • 正確剖析和載入 CSV 檔案,其中 分隔符 (字串、欄位、數據列) 會在字串分隔數據行內逸出。
  • 使用共用存取簽章來指定更精細的許可權模型,而不公開記憶體帳戶密鑰。
  • 針對 ERRORFILE 位置使用不同的記憶體帳戶(REJECTED_ROW_LOCATION)。
  • 自訂每個目標數據行的預設值,並指定要載入至特定目標數據行的源數據欄位。
  • 指定 CSV 檔案的自訂資料列終止符、欄位終止符和欄位引號
  • 指定儲存位置路徑中的通配符和多個檔案。
  • 如需數據擷取選項和最佳做法的詳細資訊,請參閱 使用 COPY 語句將數據內嵌至您的倉儲。

語法

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' } ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
)

引數

warehouse_name

如果執行作業的使用者目前倉儲是指定數據表的倉儲,則為選擇性。 如果未 指定倉儲 ,且目前倉儲上沒有指定的架構和數據表,COPY 就會失敗,並傳回錯誤訊息。

schema_name

如果執行作業之使用者的預設架構是指定數據表的架構,則為選擇性。 如果未 指定架構 ,且執行 COPY 作業之使用者的預設架構與指定數據表的架構不同,則會取消 COPY,並傳回錯誤訊息。

table_name

要複製到其中之數據表的名稱。 目標數據表必須已存在於倉儲中。

(column_list)

一或多個數據行的選擇性清單,用來將源數據欄位對應至目標數據表數據行以載入資料。

column_list 必須以括弧括住,並以逗號分隔。 資料行清單採用以下格式:

[(Column_name [default Default_value] [Field_number] [,...n])]

  • Column_name - 目標資料表中資料行的名稱。
  • Default_value - 預設值,取代輸入檔中的任何 NULL 值。 預設值適用於所有檔案格式。 當從數據行清單省略數據行或有空白輸入檔欄位時,COPY 會嘗試從輸入檔載入NULL。 預設值前面會加上關鍵字 'default'
  • Field_number - 對應至目標數據行的輸入檔欄位編號。
  • 欄位索引會從 1 開始。

未指定column_list,COPY 會根據來源和目標順序對應數據行:輸入欄位 1 會移至目標資料行 1、字段 2 會移至資料行 2 等等。

注意

在 Microsoft Fabric 中使用 Warehouse 上的 Parquet 檔案時,數據行名稱必須完全符合來源和目的地。 如果目標數據表中的數據行名稱與 parquet 檔案中的數據行名稱不同,則目標數據表數據行會填入 NULL。

未指定數據行清單時,COPY 會根據來源和目標順序對應數據行:輸入欄位 1 會移至目標資料行 1、字位 2 會移至資料行 2 等等。

外部位置

注意

目前不支援 Fabric OneLake 路徑,僅支援 BLOB 和 ADLS Gen2 儲存器帳戶。

指定包含資料之檔案的暫存位置。 目前支援 Azure Data Lake Storage (ADLS) Gen2 和 Azure Blob 儲存體:

  • Blob 儲存體的「外部位置」:https://<account\>.blob.core.windows.net/<container\>/<path\>
  • ADLS Gen2 的「外部位置」:https://<account\>.dfs.core.windows.net/<container\>/<path\>

Azure Data Lake Storage (ADLS) Gen2 可提供比 Azure Blob 儲存體 (舊版) 更為優異的效能。 盡可能考慮使用 ADLS Gen2 帳戶。

注意

Blob 端點也適用於 ADLS Gen2,且目前能夠執行最佳效能。 當驗證方法不需要 .dfs 時,請使用 .blob 端點。

  • 帳戶 - 儲存體帳戶名稱

  • 容器 - Blob 容器名稱

  • 路徑 - 資料的資料夾或檔案路徑。 位置會從容器開始。 如果指定資料夾,COPY 會從資料夾及其所有子資料夾擷取所有檔案。 COPY 會忽略隱藏的資料夾,而且除非在路徑中明確地指定,否則不會傳回開頭為底線 (_) 或句號 (.) 的檔案。 即使在使用萬用字元指定路徑時,此行為也是相同的。

通配符可以包含在路徑中

  • 萬用字元路徑名稱比對會區分大小寫
  • 萬用字元可以使用反斜線字元 (\) 逸出

注意

為獲得最佳效能,請避免指定會擴展到大量檔案的萬用字元。 如果可能,請列出多個檔案位置,而不是指定萬用字元。

您只能透過逗號分隔清單,從相同的儲存體帳戶和容器中指定多個檔案位置,例如:

  • https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

防火牆後方的外部位置

若要存取 Azure Data Lake Storage (ADLS) Gen2 和 Azure Blob 儲存體 防火牆後方位置上的檔案,適用下列必要條件:

  • 必須布建裝載倉儲之工作區的工作區身分識別。 如需如何設定工作區身分識別的詳細資訊,請參閱 工作區身分識別。
  • 您的 Entra ID 帳戶必須能夠使用工作區身分識別。
  • 您的 Entra ID 帳戶必須能夠透過 Azure 角色型訪問控制或 Data Lake ACL 存取基礎檔案。
  • 裝載倉儲的 Fabric 工作區必須新增為 資源實例規則。 如需如何使用資源實例規則新增 Fabric 工作區的詳細資訊,請參閱 資源實例規則

FILE_TYPE = { 'CSV' |'PARQUET' }

FILE_TYPE 會指定外部資料的格式。

  • CSV:指定符合 RFC 4180 標準的逗號分隔值檔案。
  • PARQUET:指定 Parquet 格式。

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL 會指定存取外部儲存體帳戶的驗證機制。 在 Microsoft Fabric 中的倉儲上,唯一支援的驗證機制是共用存取簽章 (SAS) 和記憶體帳戶密鑰 (SAK)。 使用者的 EntraID 驗證是預設的,不需要指定認證。

注意

使用公用記憶體帳戶時,不需要指定 CREDENTIAL。 根據預設,會使用執行中使用者的 Entra 識別碼。

  • 使用共用存取簽章進行驗證 (SAS)

    • IDENTITY:值為「共用存取簽章」的常數
    • SECRET:共用存取簽章會提供記憶體帳戶中資源的委派存取權。
    • 所需最小權限:READ 和 LIST
  • 使用記憶體帳戶金鑰進行驗證

    • IDENTITY:值為「儲存體帳戶金鑰」的常數
    • SECRET:儲存體帳戶金鑰

ERRORFILE = 目錄位置

ERRORFILE 僅適用於 CSV。 指定應該寫入拒絕的數據列和對應的錯誤檔案的目錄。 您可以指定儲存體帳戶的完整路徑,或指定相對於容器的路徑。 如果指定的路徑不存在,則會代表您建立一個路徑。 系統會建立名稱為 "_rejectedrows" 的子目錄。 "_" 字元可確保該目錄從其他資料處理逸出,除非已明確在位置參數中指名。

注意

當相對路徑傳遞至 ERRORFILE 時,路徑會相對於external_location中指定的容器路徑。

在此目錄中,會有一個根據載入提交時間建立的資料夾,格式為 YearMonthDay -HourMinuteSecond (例如 20180330-173205)。 在此資料夾中,會建立具有語句標識碼的資料夾,並在該資料夾底下寫入兩種類型的檔案:錯誤。包含拒絕原因的 Json 檔案,以及包含已拒絕數據列的row.csv檔案。

如果 ERRORFILE 已定義記憶體帳戶的完整路徑,則會使用ERRORFILE_CREDENTIAL來連線到該記憶體。 否則會使用 CREDENTIAL 所述的值。 當源數據所使用的相同認證用於 ERRORFILE 時,也會套用至ERRORFILE_CREDENTIAL的限制。

ERRORFILE_CREDENTIAL = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL 僅適用於 CSV 檔案。 在 Microsoft Fabric 中的倉儲上,唯一支援的驗證機制是共用存取簽章(SAS)。

  • 使用共用存取簽章進行驗證 (SAS)
    • IDENTITY:值為「共用存取簽章」的常數
    • SECRET:共用存取簽章會提供記憶體帳戶中資源的委派存取權。
    • 所需最小權限:READ、LIST、WRITE、CREATE、DELETE

注意

如果您要將相同的儲存體帳戶用於 ERRORFILE,並指定相對於容器根目錄的 ERRORFILE 路徑,則不需要指定 ERROR_CREDENTIAL。

MAXERRORS = max_errors

MAXERRORS 指定 COPY 作業失敗之前,載入中允許的拒絕數據列數目上限。 COPY 作業無法匯入的每個數據列都會被忽略,並計算為一個錯誤。 如果未指定max_errors,則預設值為 0。

在 Microsoft Fabric 中,FILE_TYPE為 'PARQUET' 時,無法使用 MAXERRORS

COMPRESSION = { 'Snappy' |'GZIP' |'NONE'}

COMPRESSION 是選用的,而且會指定外部資料的資料壓縮方法。

  • CSV 支援 GZIP
  • Parquet 支援 GZIP 和 Snappy

COPY 命令會在未指定此參數時,根據擴展名自動偵測壓縮類型:

  • .gz - GZIP

目前僅支援 PARSER_VERSION 1.0 載入壓縮檔案。

COPY 命令要求 gzip 檔案不包含任何尾端垃圾才能正常運作。 gzip 格式嚴格要求檔案由有效的成員組成,而不需要在檔案之前、之間或之後提供任何其他資訊。 此格式的任何偏差,例如尾端非 gzip 資料的存在,都會導致 COPY 命令失敗。 請務必確認 gzip 檔案結尾沒有尾端垃圾,以確保 COPY 可以成功處理這些檔案。

FIELDQUOTE = 'field_quote'

FIELDQUOTE 僅適用於 CSV。 指定在 CSV 檔案中做為引號字元(字串分隔符)的單一字元。 如果未指定,則會使用引號字元 (“) 作為 RFC 4180 標準中所定義的引號字元。 FIELDQUOTE 也支援十六進位表示法。 FIELDQUOTE 的UTF-8不支援擴充 ASCII 和多位元組字元。

注意

FIELDQUOTE 字元會在有雙 FIELDQUOTE (分隔符號) 存在的字串資料行中逸出。

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR 僅適用於 CSV。 指定 CSV 檔案中使用的欄位終止符。 欄位終止符也可以使用十六進位表示法來指定。 欄位結束字元可以是多個字元。 預設的欄位結束字元為 (,)。 FIELDTERMINATOR 的 UTF-8 不支援擴充 ASCII 和多位元組字元。

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR 僅適用於 CSV。 指定 CSV 檔案中使用的數據列終止符。 您可以使用十六進位標記法來指定資料列結束字元。 資料列結束字元可以是多個字元。 預設結束符為 \r\n\n\r

COPY 命令 \r 會在指定 \n 時前置字元(換行符),以產生 \r\n。 若要只 \n 指定字元,請使用十六進位表示法 (0x0A)。 在十六進位中指定多字元數據列終止符時,請勿在每個字元之間指定 0x。

ROWTERMINATOR 的UTF-8不支援擴充 ASCII 和多位元組字元。

FIRSTROW = First_row_int

FIRSTROW 僅適用於 CSV。 指定 COPY 命令所有檔案中先讀取的數據列編號。 值會從 1 開始,也就是預設值。 如果將值設定為二,則在載入資料時,會略過每個檔案中的第一個資料列 (標題列)。 如果資料列存在資料列結束字元,就會略過。

ENCODING = 'UTF8' | 'UTF16'

ENCODING 僅適用於 CSV。 預設值為 UTF8。 指定 COPY 命令所載入之檔案的資料編碼標準。

PARSER_VERSION = { '1.0' |'2.0' }

PARSER_VERSION僅適用於 CSV。 預設值為 2.0。 指定來源檔類型為 CSV 時用於擷取的檔案剖析器。 2.0 剖析器提供改善的效能來擷取 CSV 檔案。

剖析器 2.0 版有下列限制:

  • 不支援壓縮的 CSV 檔案
  • 不支援使用UTF-16編碼的檔案
  • 不支援多重字元或多位元組ROWTERMINATOR、FIELDTERMINATOR或FIELDQUOTE。 不過,'\r\n' 會接受為預設 ROWTERMINATOR

在搭配UTF-8檔案使用剖析器1.0版時,FIELDTERMINATOR不支援多位元組和多字元終止符。

剖析器 1.0 版僅適用於回溯相容性,而且只有在遇到這些限制時才使用。

注意

當 COPY INTO 與壓縮的 CSV 檔案或具有 UTF-16 編碼的檔案搭配使用時,COPY INTO 會自動切換至 PARSER_VERSION 1.0,而不需要用戶動作。 對於 FIELDTERMINATOR 或 ROWTERMINATOR 上的多字元終止符,COPY INTO 語句將會失敗。 如果需要多字元分隔符,請使用 PARSER_VERSION = '1.0'。

備註

WAREHOUSE 中的 COPY INTO 不允許設定用來解譯日期字元字串的日期格式。 根據預設,所有日期都會被視為具有月-日-年格式。 若要擷取具有不同日期格式的 CSV 檔案,請使用 SET DATEFORMAT 在會話層級指定所需的日期格式。 如需詳細資訊,請參閱 SET DATEFORMAT (Transact-SQL)

此外,COPY 語句只接受數據列數據和命令參數的 UTF-8 和 UTF-16 有效字元。 使用無效字元的原始程式檔或參數(例如 ROW TERMINATOR 或 FIELD TERMINATOR)可能會被 COPY 語句錯誤解譯,並導致數據損毀或其他失敗等非預期的結果。 在叫用 COPY 語句之前,請確定您的來源檔案和參數符合 UTF-8 或 UTF-16 規範。

範例

如需在 Microsoft Fabric 中使用 WAREHOUSE INTO 的詳細資訊,請參閱 使用 COPY 語句將數據內嵌至您的倉儲。

A. 從公用儲存體帳戶載入

下列範例是 COPY 命令的最簡單形式,它會從公用儲存體帳戶載入資料。 在此範例中,COPY 陳述式的預設值符合行項目 csv 檔案的格式。

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'

COPY 命令的預設值為:

  • MAXERRORS = 0

  • COMPRESSION 預設值為未壓縮

  • FIELDQUOTE = '“'

  • FIELDTERMINATOR = ','

  • ROWTERMINATOR = '\n'

重要

COPY 會在 \n 內部視為 \r\n 。 如需詳細資訊,請參閱 ROWTERMINATOR 一節。

  • FIRSTROW = 1

  • ENCODING = 'UTF8'

  • FILE_TYPE = 'CSV'

B. 透過共用存取簽章 (SAS) 載入驗證

下列範例會載入使用換行字元作為資料列結束字元的檔案,如 UNIX 輸出。 此範例也會使用 SAS 金鑰向 Azure Blob 儲存體進行驗證。

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. 使用具有透過記憶體帳戶金鑰進行驗證之預設值的資料列清單載入 (SAK)

此範例會載入使用預設值指定資料行清單的檔案。

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_account_key>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. 載入 Parquet

這個範例會使用通配符,使用執行中使用者的 EntraID,在資料夾下載入所有 Parquet 檔案。

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
)

E. 透過指定萬用字元和多個檔案來載入

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    FIELDTERMINATOR = '|'
)

常見問題集

COPY 命令載入壓縮 CSV 檔案的檔案分割指導方針為何?

請考慮分割大型 CSV 檔案,特別是在檔案數目很小時,但每個檔案至少保留 4 MB,以提升效能。

載入 Parquet 檔案之 COPY 命令的檔案分割指引為何?

請考慮分割大型 Parquet 檔案,特別是當檔案數目很小時。

檔案的數目或大小是否有任何限制?

檔案的數目或大小沒有限制,但為了獲得最佳效能,我們建議檔案至少為 4 MB。

當我未指定認證時,會使用何種驗證方法?

根據預設, COPY INTRO 將會使用執行中使用者的 Entra 識別碼。