COPY INTO （Transact-SQL）

Tip

Microsoft Fabric Data Warehouse是数据湖基础上的企业规模关系仓库，具有未来就绪的体系结构、内置 AI 和新功能。如果不熟悉数据仓库，请从Fabric Data Warehouse开始。现有的指定 SQL 池工作负荷可以升级到 Fabric，以跨数据科学、实时分析和报告访问新功能。

本文介绍如何在 Azure Synapse Analytics 中使用 COPY 语句从外部存储帐户加载数据。该 COPY 声明为高吞吐量数据导入 Azure Synapse Analytics 提供了最大的灵活性。

Note

有关 Microsoft Fabric 中的仓库，请参阅 COPY INTO。

用于 COPY 以下功能：

使用特权较低的用户加载数据，而无需对数据仓库拥有严格的 CONTROL 权限。
执行单个 T-SQL 语句，不需要创建任何其他数据库对象。
正确分析和加载 分隔符 （字符串、字段、行）在字符串分隔列中转义的 CSV 文件。
使用共享访问签名（SAS）指定一个更简单的权限模型，而无需公开存储帐户密钥。
使用不同的存储账户来存放位置（ERRORFILEREJECTED_ROW_LOCATION）。
为每个目标列自定义默认值，并指定要加载到特定目标列中的源数据字段。
为CSV文件指定自定义行终止符、字段终止符和字段引号。
对 CSV 文件使用SQL Server日期格式。
在存储位置路径中指定通配符和多个文件。
自动架构发现简化了将源数据定义和映射到目标表的过程。
自动表创建过程会自动创建表，并与自动架构发现一起工作。
直接将 Parquet 文件中的复杂数据类型（如地图和列表）加载到字符串列中，而无需使用其他工具来预处理数据。

Note

若要从 Parquet 文件加载复杂数据类型，请使用 <a0/> 打开自动创建表。

有关使用 COPY 语句的综合示例和快速入门，请参阅：

Note

Microsoft Entra ID 以前称为 Azure Active Directory (Azure AD)。

Syntax

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' } ]
)

Arguments

schema_name

如果执行操作的用户的默认架构是指定表的架构，则为可选。如果未指定架构，并且执行 COPY 操作的用户的默认架构与指定表的架构不同，则会 COPY 取消该操作并返回错误消息。

表名

要将数据复制到其中的表的名称。目标表可以是临时或永久表，并且必须已存在于数据库中。对于自动架构检测模式，请不要提供列列表。

（column_list）

包含一列或多列的可选列表，用于将源数据字段映射到目标表列以加载数据。

在情况下，请勿指定 column_list。

必须用括号将 column_list 括起来，并且用逗号进行分隔。列列表的格式如下：

[（Column_name [默认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 存储的外部位置：
ADLS Gen2 的外部位置：

Note

该 .blob 终结点也可用于 ADLS Gen2，目前会产生最佳性能。当身份验证方法不需要时.dfs，.blob请使用终结点。

Account：存储帐户名称
Container：blob 容器名称
Path：数据的文件夹或文件路径。位置从容器开始。如果指定文件夹， COPY 则从文件夹及其所有子文件夹中检索所有文件。 COPY 忽略隐藏的文件夹，并且不会返回以下划线（_）或句点（）开头的文件，.除非在路径中明确指定。即使使用通配符指定路径也是如此。

可以在路径中包含通配符，其中：

通配符路径名称匹配区分大小写
可以使用反斜杠字符（\）转义通配符
通配符扩展以递归方式应用。例如，以下示例中加载了（包括子目录Customer1）下Customer1的所有 CSV 文件：Account/Container/Customer1/*.csv

Note

为获得最佳性能，请避免指定在更大数量的文件中扩展的通配符。如有可能，请列出多个文件位置，而不是指定通配符。

只能通过逗号分隔的列表从同一存储帐户和容器指定多个文件位置，例如：

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：指定优化行纵栏表 (ORC) 格式。

Note

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/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS（blob ¹）/MSI （dfs ² ）/服务主体/密钥/Entra	SAS（blob ¹）/MSI （dfs ² ）/服务主体/密钥/Entra

¹ 此身份验证方法需要外部位置路径中的 blob 终结点（.blob.core.windows.net）。

² 此身份验证方法需要外部位置路径中的 dfs 终结点（.dfs.core.windows.net）。

Note

使用 Microsoft Entra ID 或公共存储帐户进行身份验证时，无需指定 CREDENTIAL。
如果存储帐户与 VNet 相关联，则必须使用托管标识进行身份验证。

使用共享访问签名 (SAS) 进行身份验证
- ：值为的常量
- SECRET：共享访问签名提供对存储帐户中资源的委派访问权限。
所需的最低权限：READ 和 LIST
使用服务主体进行身份验证
- IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
- SECRET：Microsoft Entra应用程序服务主体密钥
所需的最小 RBAC 角色：存储 blob 数据参与者、存储 blob 数据所有者或存储 blob 数据读取者
使用存储帐户密钥进行身份验证
- ：值为的常量
- SECRET：存储帐户密钥
使用托管标识（VNet 服务终结点）进行身份验证
- ：值为的常量
所需的最低 RBAC 角色：在 Azure 中注册的 Microsoft Entra 逻辑服务器的存储 blob 数据参与者或存储 blob 数据所有者。使用未与 Synapse 工作区关联的专用 SQL 池（以前为 SQL DW）时，不需要此 RBAC 角色，但托管标识需要对目标对象具有访问控制列表（ACL）权限才能启用对源文件的读取访问权限。
使用 Microsoft Entra 用户进行身份验证
- 不需要 CREDENTIAL
所需的最低 RBAC 角色：Microsoft Entra 用户的存储 blob 数据参与者或存储 blob 数据所有者

ERRORFILE = 目录位置

ERRORFILE 仅适用于 CSV。它指定语句中的 COPY 目录，其中写入了拒绝的行和相应的错误文件。可以从存储帐户或相对于容器的路径指定完整路径。如果指定的路径不存在，则仓库将创建一个路径。使用名称 _rejectedrows创建子目录。该 _ 字符可确保目录转义以供其他数据处理，除非在位置参数中显式命名。

Note

将相对路径 ERRORFILE传递给时，使其相对于 在external_location中指定的容器路径。

在此目录中，仓库根据加载提交格式 YearMonthDay -HourMinuteSecond （例如， 20180330-173205）创建一个文件夹。在此文件夹中，进程写入两种类型的文件：原因（错误）文件和数据（行）文件。每个文件前面都附加queryIDdistributionID了一个 GUID 和一个文件 GUID。数据和原因位于不同的文件中，因此相应的文件具有匹配的前缀。

如果 ERRORFILE 定义了存储帐户的完整路径， COPY 则用于 ERRORFILE_CREDENTIAL 连接到该存储。否则，它将使用指定的 CREDENTIAL值。对源数据使用相同的凭据时， ERRORFILE也适用 ERRORFILE_CREDENTIAL 限制。

ERRORFILE_CREDENTIAL = （IDENTITY = ''， SECRET = ''）

ERRORFILE_CREDENTIAL 仅适用于 CSV 文件。支持的数据源和身份验证方法包括：

Azure Blob 存储：SAS、服务主体或Microsoft Entra
Azure Data Lake Gen2：SAS、MSI、服务主体或Microsoft Entra
使用共享访问签名 (SAS) 进行身份验证
- ：值为的常量
- SECRET：共享访问签名提供对存储帐户中资源的委派访问权限。
所需的最低权限：READ、LIST、WRITE、CREATE、DELETE
使用服务主体进行身份验证
- IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
- SECRET：Microsoft Entra应用程序服务主体密钥
所需的最小 RBAC 角色：存储 blob 数据参与者或存储 blob 数据所有者

Note

使用 OAuth 2.0 令牌终结点 V1

使用托管标识（VNet 服务终结点）进行身份验证
- ：值为的常量
所需的最低 RBAC 角色：Microsoft Entra 已注册SQL 数据库服务器的存储 blob 数据参与者或存储 blob 数据所有者
使用 Microsoft Entra 用户进行身份验证
- CREDENTIAL 不需要
所需的最低 RBAC 角色：Microsoft Entra 用户的存储 blob 数据参与者或存储 blob 数据所有者

不支持使用存储帐户 ERRORFILE_CREDENTIAL 密钥。

Note

如果对错误文件使用相同的存储帐户并指定ERRORFILE相对于容器根路径的路径，则无需指定。ERROR_CREDENTIAL

MAXERRORS = max_errors

MAXERRORS 指定 COPY 操作失败之前加载中允许的最大拒绝行数。 COPY 操作无法导入的每一行都将被忽略并计为一个错误。如果未指定最大错误数的值，则默认值为 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 - 活泼
.deflate - DefaultCodec （仅 Parquet 和 ORC）

COPY 命令要求 gzip 文件不包含任何尾随垃圾才能正常运行。 gzip 格式严格要求文件由有效成员组成，而无需在文件之前、之间或之后提供任何其他信息。与此格式的任何偏差（例如存在尾随非 gzip 数据）会导致 COPY 命令失败。若要确保 COPY 成功运行，请确保在 gzip 文件末尾没有尾随垃圾。

FIELDQUOTE = “field_quote”

FIELDQUOTE 适用于 CSV，并指定在 CSV 文件中用作引号字符（字符串分隔符）的单个字符。如果未指定此值，则引号字符（"）用作 RFC 4180 标准中定义的引号字符。也支持 FIELDQUOTE十六进制表示法。 UTF-8 FIELDQUOTE不支持扩展 ASCII 和多字节字符。

Note

FIELDQUOTE 字符在字符串列中进行转义，其中存在双 FIELDQUOTE （分隔符）。

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR 仅适用于 CSV。指定 CSV 文件中使用的字段终止符。可以使用十六进制表示法指定字段终止符。字段终止符可以是多字符。默认字段终止符为（,）。 UTF-8 FIELDTERMINATOR不支持扩展 ASCII 和多字节字符。

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR 仅适用于 CSV。指定 CSV 文件中使用的行终止符。可以使用十六进制表示法指定行终止符。行终止符可以是多字符。默认情况下，行终止符为 \r\n。

当指定 \r（换行符）以生成 \n 时，COPY 命令会为 \r\n 字符加上前缀。要仅指定 \n 字符，请使用十六进制表示法 (0x0A)。在十六进制中指定多字符行终止符时，不要在每个字符之间指定 0x 。

UTF-8 ROWTERMINATOR不支持扩展 ASCII 和多字节字符。

FIRSTROW = First_row_int

FIRSTROW 适用于 CSV，并指定在 COPY 命令的所有文件中首先读取的行号。值从值开始 1，这是默认值。如果将值 2设置为，则加载数据时会跳过每个文件（标题行）中的第一行。如果有行终止符，则跳过该行。

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 指定导入数据文件中的标识值还是要用于标识列的值。 OFF 如果是IDENTITY_INSERT（默认值），则会验证此列的标识值，但不会导入。请注意 COPY 命令的以下行为：

如果 IDENTITY_INSERT 为 OFF，并且表具有标识列
- 必须指定不将输入字段映射到标识列的列列表。
如果 IDENTITY_INSERT 为 ON，并且表具有标识列
- 如果传递列列表，则必须将输入字段映射到标识列。
列列表中的 IDENTITY 列不支持默认值。
一次只能设置 IDENTITY_INSERT 一个表。

Azure Synapse Analytics 会根据创建表时指定的种子和增量值自动分配唯一值。

AUTO_CREATE_TABLE = { 'ON' |'OFF' }

AUTO_CREATE_TABLE 指定是否可以通过与自动架构发现一起自动创建表。 AUTO_CREATE_TABLE仅适用于 Azure Synapse Analytics 中的 Parquet 文件。

ON：启用自动表创建。此过程 COPY INTO 通过发现要加载的文件的结构自动创建新表。还可以将其与预先存在的表一起使用，以利用 Parquet 文件的自动架构发现。
OFF：未启用自动表创建。 Default.

Note

自动表创建与自动架构发现一起工作。默认情况下，不会启用自动表创建。

Permissions

运行 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];

Remarks

该 COPY 语句仅接受 UTF-8 和 UTF-16 的有效字符用于行数据和命令参数。该 COPY 语句可能会错误地解释使用无效字符的源文件或参数（如 ROWTERMINATOR 或 FIELDTERMINATOR），并导致意外结果，例如数据损坏或其他故障。在调用该 COPY 语句之前，确保你的源文件和参数符合 UTF-8 或 UTF-16 标准。

查询 MAXDOP 提示不支持 COPY INTO。

若要确保可靠的执行，请勿在操作过程中 COPY INTO 更改源文件和文件夹。

在命令运行时修改、删除或替换任何引用的文件或文件夹可能会导致作失败或导致数据引入不一致。
在执行 COPY INTO之前，请验证所有源数据是否稳定，并且在此过程中不会更改。

如果源数据精度高于目标列定义，则数值、日期和时间类型的值将被截断，而不是舍入。

Examples

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'

Important

COPY 视 \n 为 \r\n 内在。有关详细信息，请参阅 ROWTERMINATOR 部分。

FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'
IDENTITY_INSERT = 'OFF'

以下示例加载将换行符用作行终止符的文件，例如 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>'),
    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'
)

FAQ

COPY 命令的性能与 PolyBase 有何比较？

根据工作负荷，COPY 命令的性能可能更好。

仓库无法自动拆分压缩文件。为了获得最佳加载性能，请考虑在加载压缩的 CSV 时将输入拆分为多个文件。
仓库可以自动拆分大型未压缩的 CSV 文件进行并行加载，因此通常不需要手动拆分未压缩的 CSV 文件。在某些情况下，由于数据特征，自动文件拆分不可行，手动拆分大型 CSV 仍可能会提高性能。

加载压缩 CSV 文件时，COPY 命令的文件拆分指导是什么？

下表概述了应使用的文件数。达到建议的文件数时，可以使用较大的文件获得更好的性能。文件数由计算节点数乘以 60 确定。例如，在 6000 DWU 中，有 12 个计算节点，因此有 12 * 60 = 720 个分区。有关简单的文件拆分体验，请参阅如何使用文件拆分最大程度地提高 COPY 加载吞吐量。

DWU	文件的数目
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

加载 Parquet 或 ORC 文件时，COPY 命令的文件拆分指导是什么？

无需拆分 Parquet 和 ORC 文件，因为 COPY 命令会自动拆分文件。为了获得最佳性能，Azure存储帐户中的 Parquet 和 ORC 文件应为 256 MB 或更大。

文件的数量和大小有限制吗？

文件的数量或大小没有限制。但是，为了获得最佳性能，请使用至少 4 MB 的文件。此外，将源文件计数限制为最多 5,000 个文件，以提高性能。

COPY 语句是否存在已知问题？

如果你有在 2020 年 12 月 7 日之前创建的Azure Synapse工作区，则使用托管标识进行身份验证时可能会遇到类似的错误消息：com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

若要解决此问题，请重新注册工作区的托管标识：

安装 Azure PowerShell 中的说明进行操作。请参阅安装 PowerShell。

使用 PowerShell 注册工作区的托管标识：

Connect-AzAccount
Select-AzSubscription -SubscriptionId <subscriptionId>
Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity

使用 Azure Synapse Analytics 加载概述

适用于：Microsoft Fabric 中的仓库

本文介绍如何在 Microsoft Fabric 中使用 Warehouse 中的 COPY 语句从外部存储帐户加载。 COPY 语句为将高吞吐量数据引入Microsoft Fabric提供最大的灵活性，并且是将数据引入到 Microsoft Fabric 仓库的策略。

在 Fabric Data Warehouse 中，COPY 语句当前支持 CSV、JSONL 和 PARQUET 文件格式。对于数据源，支持Azure Data Lake Storage Gen2帐户和 OneLake 源。

有关在 Microsoft Fabric 中使用仓库的详细信息 COPY INTO ，请参阅使用 COPY 语句在 Microsoft Fabric 中引入数据仓库中的数据。

默认情况下，COPY INTO作为执行Microsoft Entra ID用户进行身份验证。

用于 COPY 以下功能：

使用特权较低的用户加载数据，而无需对仓库拥有严格的 CONTROL 权限。
执行单个 T-SQL 语句，不需要创建任何其他数据库对象。
正确分析和加载 CSV 文件，其中分隔符（字符串、字段、行）在字符串分隔列中进行转义
正确分析和加载 JSONL 文件，其中每行都是有效的 JSON 对象，字段是使用 JSON 路径表达式映射的。
使用共享访问签名（SAS）指定一个更简单的权限模型，而无需公开存储帐户密钥。
使用不同的存储账户来存放位置（ERRORFILEREJECTED_ROW_LOCATION）。
为每个目标列自定义默认值，并指定要加载到特定目标列中的源数据字段。
为CSV文件指定自定义行终止符、字段终止符和字段引号。
在存储位置路径中指定通配符和多个文件。
有关数据引入选项和最佳做法的详细信息，请参阅使用 COPY 语句在 Microsoft Fabric 中将数据引入仓库。

Syntax

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'JSONL' | '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 ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

如果执行操作的用户的当前仓库是指定表的仓库，则为可选。如果未指定仓库，并且当前仓库上不存在指定的架构和表， COPY 则失败并返回错误消息。

schema_name

如果执行操作的用户的默认架构是指定表的架构，则为可选。如果未指定架构，并且执行 COPY 操作的用户的默认架构与指定表的架构不同， COPY 则取消，并返回错误消息。

表名

表的名称被 COPY 数据输入。目标表必须已存在于仓库中。

（column_list）

用于在数据加载期间将源数据字段映射到目标表列的列的可选列表。

必须用括号将 column_list 括起来，并且用逗号进行分隔。语法为：

[（Column_name [默认Default_value] [Field_number |JSON_path] [,...n])]

Column_name：目标表中列的名称。
Default_value - 替代输入文件中任意 NULL 值的默认值。默认值适用于所有文件格式。 COPY 当列列表中遗漏某列或输入文件字段为空时，尝试从输入文件加载 NULL 。默认值前面有关键字“default”
Field_number - 仅适用于 CSV 文件。指定字段在输入数据中的序号位置。字段索引从 1 开始。
JSON_path - 仅适用于 JSONL 文件。指定一个 JSON 路径表达式，该表达式标识要从每个 JSON 对象中提取的字段（例如， $.CustomerName）。

如果未指定 column_list， COPY 则根据源顺序和目标顺序映射列：输入字段 1 将转到目标列 1、字段 2 转到列 2，依如此。

Note

在 Microsoft Fabric 中的仓库上使用 Parquet 文件时，列名称必须在源和目标中完全匹配。如果目标表中的列名称与 parquet 文件中的列名称不同，则目标表列将填充 NULL。

如果未指定列列表， COPY 则根据源顺序和目标顺序映射列：输入字段 1 将转到目标列 1、字段 2 转到列 2，依如此。

外部位置

指定包含数据的暂存文件的位置。目前支持 Azure Data Lake Storage（ADLS） Gen2、Azure Blob 存储和 OneLake：

Blob 存储的外部位置：
ADLS Gen2 的外部位置：
OneLake 的外部位置：https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage (ADLS) Gen2 提供的性能优于Azure Blob 存储（旧版）。尽可能考虑使用 ADLS Gen2 帐户。

Note

该 .blob 终结点也可用于 ADLS Gen2，目前会产生最佳性能。当身份验证方法不需要时dfs，blob请使用终结点。

Account：存储帐户名称
Container：blob 容器名称
Path：数据的文件夹或文件路径。位置从容器开始。如果指定文件夹， COPY 则从文件夹及其所有子文件夹中检索所有文件。 COPY 忽略隐藏的文件夹，并且不会返回以下划线（_）或句点（）开头的文件，.除非在路径中明确指定。即使使用通配符指定路径也是如此。

可以在路径中使用通配符，其中

通配符路径名称匹配区分大小写
可以使用反斜杠字符（\）转义通配符

Note

为获得最佳性能，请避免指定在更大数量的文件中扩展的通配符。如有可能，请列出多个文件位置，而不是指定通配符。

只能通过逗号分隔的列表从同一存储帐户和容器指定多个文件位置，例如：

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 基于角色的访问控制（RBAC）或 Data Lake ACL 访问基础文件。
托管仓库的 Fabric 工作区必须添加为 资源实例规则。有关如何使用资源实例规则添加 Fabric 工作区的详细信息，请参阅资源实例规则。

FILE_TYPE = { 'CSV' |“JSONL” |'PARQUET' }

FILE_TYPE 指定外部数据的格式。

CSV：指定符合 RFC 4180 标准的逗号分隔值文件。
JSONL：指定换行分隔的 JSON（JSON 行）文件，其中每行都是有效的 JSON 对象。
PARQUET：指定 Parquet 格式。

CREDENTIAL （IDENTITY = ''， SECRET = ''）

CREDENTIAL 指定用于访问外部存储帐户的身份验证机制。

在 Fabric 数据仓库中：

COPY INTO 不支持禁用公共访问的位置。
对于公共存储帐户，支持的身份验证机制是 Microsoft Entra ID、共享访问签名（SAS）或存储帐户密钥（SAK）。
对于防火墙后面的公共存储帐户，Microsoft Entra ID 身份验证是唯一受支持的身份验证方法。 COPY INTO 使用 OneLake 作为源仅支持 EntraID 身份验证。

用户的Microsoft Entra ID身份验证是默认的。无需指定凭据。

使用共享访问签名进行身份验证（SAS）
- IDENTITY：值为 . Shared Access Signature.
- SECRET：共享访问签名提供对存储帐户中资源的委派访问权限。
- 所需的最低权限：READ 和 LIST。
使用存储帐户密钥进行身份验证
- IDENTITY：值为 . Storage Account Key.
- SECRET：存储帐户密钥。

ERRORFILE = 目录位置

ERRORFILE 适用于 CSV 和 JSONL。指定目录，应在该目录中写入被拒绝的行和相应的错误文件。可以从存储帐户或相对于容器的路径指定完整路径。如果指定的路径不存在，系统将代表你创建一个路径。使用名称 _rejectedrows创建子目录。该 _ 字符可确保目录转义以供其他数据处理，除非在位置参数中显式命名。

Note

将相对路径 ERRORFILE传递给时，使其相对于 在external_location中指定的容器路径。

在此目录中，仓库根据加载提交格式 YearMonthDay -HourMinuteSecond （例如， 20180330-173205）创建一个文件夹。在此文件夹中，仓库创建一个包含语句 ID 的文件夹，在该文件夹中，将写入两种类型的文件：错误。包含拒绝原因的 Json 文件，以及包含已拒绝行的 row.csv 文件。

如果 ERRORFILE 定义了存储帐户的完整路径，则 ERRORFILE_CREDENTIAL 使用该路径连接到该存储。否则，将使用前面 CREDENTIAL 提到的值。当用于源数据的 ERRORFILE相同凭据时，同样适用的限制 ERRORFILE_CREDENTIAL 也适用。

使用受防火墙保护的 Azure 存储帐户时，错误文件是在存储帐户路径中指定的同一容器中创建的。在此方案中考虑使用 ERRORFILE 此选项时，还需要指定 MAXERROR 参数。如果 ERRORFILE 定义了存储帐户的完整路径，则 ERRORFILE_CREDENTIAL 使用该路径连接到该存储。否则，将使用前面 CREDENTIAL 提到的值。

ERRORFILE_CREDENTIAL = （IDENTITY = ''， SECRET = ''）

ERRORFILE_CREDENTIAL 适用于 CSV 和 JSONL 文件。在 Microsoft Fabric 中的仓库上，唯一支持的身份验证机制是共享访问签名 (SAS)。

使用共享访问签名进行身份验证（SAS）
- ：值为的常量
- SECRET：共享访问签名提供对存储帐户中资源的委派访问权限。
所需的最低权限：READ、LIST、WRITE、CREATE、DELETE

Note

如果对错误文件使用相同的存储帐户并指定ERRORFILE相对于容器根路径的路径，则无需指定。ERROR_CREDENTIAL

MAXERRORS = max_errors

MAXERRORS 适用于 CSV 和 JSONL。指定在操作失败之前 COPY 加载中允许的最大拒绝行数。每一行作无法导入的行 COPY 都会被忽略，并计入一次错误。如果未指定最大错误数，则默认值为 0。

在 Fabric Data Warehouse 中，当 FILE_TYPE 为 PARQUET 时，不能使用 MAXERRORS。

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

COMPRESSION 是可选的，指定外部数据的数据压缩方法。

CSV 支持 GZIP。
Parquet 支持 GZIP 和 Snappy。
JSONL 不支持

当未指定该参数时，命令 COPY 会自动检测基于文件扩展名的压缩类型：

.gz - Gzip

目前仅分析器版本 1.0 支持加载压缩文件。

该 COPY 命令要求 gzip 文件不包含任何尾随垃圾才能正常运行。 gzip 格式严格要求文件由有效成员组成，而无需在文件之前、之间或之后提供任何其他信息。与此格式的任何偏差（例如存在尾随非 gzip 数据）都会导致命令失败 COPY 。若要确保 COPY 成功运行，请确保在 gzip 文件末尾没有尾随垃圾。

FIELDQUOTE = “field_quote”

FIELDQUOTE 仅适用于 CSV。它指定一个字符，该字符用作 CSV 文件中的引号字符（字符串分隔符）。如果未指定 FIELDQUOTE，则引号字符（"）用作 RFC 4180 标准中定义的引号字符。也支持 FIELDQUOTE十六进制表示法。 UTF-8 FIELDQUOTE不支持扩展 ASCII 和多字节字符。

Note

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。

UTF-8 ROWTERMINATOR不支持扩展 ASCII 和多字节字符。

FIRSTROW = First_row_int

FIRSTROW 仅适用于 CSV。指定命令所有文件 COPY 中最先读取的行号。值从值开始 1，这是默认值。如果将值 2设置为，则加载数据时会跳过每个文件（标题行）中的第一行。如果有行终止符，则跳过该行。

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

DATEFORMAT 适用于 CSV 和 JSONL。指定日期映射到SQL Server日期格式的日期格式。有关所有 Transact-SQL 日期和时间数据类型及函数的概述，请参阅日期和时间数据类型及函数 (Transact-SQL)。命令中的 COPY DATEFORMAT 优先于会话级别配置的 DATEFORMAT。

ENCODING = 'UTF8' |“UTF16”

ENCODING 适用于 CSV 和 JSONL。默认值为 UTF8。指定命令加载文件 COPY 的数据编码标准。

PARSER_VERSION = { '1.0' |'2.0' }

PARSER_VERSION 仅适用于 CSV 文件。默认值为 2.0。 PARSER_VERSION 指定在源文件类型为 CSV 时用于引入的文件分析器。 2.0 分析程序为引入 CSV 文件提供了改进的性能。

分析器版本 2.0 具有以下限制：

不支持压缩的 CSV 文件。
不支持使用 UTF-16 编码的文件。
多字符或多字节 ROWTERMINATOR， FIELDTERMINATOR或 FIELDQUOTE 不受支持。然而，被 \r\n 默认接受 ROWTERMINATOR。

将分析器版本 1.0 与 UTF-8 文件一起使用时，不支持 FIELDTERMINATOR多字节和多字符终止符。

分析器版本 1.0 仅适用于向后兼容性。仅在遇到这些限制时使用它。

Note

将压缩的 CSV 文件或带有 UTF-16 编码的文件一起使用 COPY INTO 时，无需用户操作即可 COPY INTO 自动切换到 PARSER_VERSION 1.0。对于多字符终止符 FIELDTERMINATOR ，或者 ROWTERMINATOR语句 COPY INTO 失败。如果需要多字符分隔符，请使用 PARSER_VERSION = '1.0' 。

MATCH_COLUMN_COUNT = { 'ON' |'OFF' }

MATCH_COLUMN_COUNT 仅适用于 CSV 文件。默认值为 OFF. 它指定命令是否 COPY 应检查源文件中的列计数行是否与目标表的列计数匹配。以下行为适用：

如果 MATCH_COLUMN_COUNT 为 OFF：
- 此命令将忽略超出源行中的列。
  - 该命令在行的可为 null 列中插入 NULL 值，这些行的列数较少。
- 如果未向不可为 null 的列提供值，则该 COPY 命令将失败。
如果 MATCH_COLUMN_COUNT 为 ON：
- 该 COPY 命令检查源文件中每个行的列数是否与目标表的列数相符。
如果列计数不匹配，命令 COPY 将失败。

Note

MATCH_COLUMN_COUNT 独立于 MAXERRORS. 无论怎样MAXERRORS，列计数不匹配都会导致COPY INTO失败。

将 COPY INTO 与 OneLake 配合使用

使用 COPY INTO 直接从存储在 Fabric OneLake 中的文件（现有项下）加载数据。此方法无需使用外部暂存帐户（如 ADLS Gen2 或 Blob 存储），并使用Fabric权限启用工作区管理的 SaaS 本机引入。此功能支持：

从工作区和项中的任何位置读取
同一租户中的工作区到仓库负载
使用Microsoft Entra ID实现本机标识

Example:

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Permissions

控制平面权限

若要执行该COPY INTO命令，必须通过“管理工作区”中的访问权限（至少具有查看器角色）授予工作区角色的成员身份。或者，可以通过 Fabric 门户中的 Item 权限与用户共享仓库访问权限，至少具有读取权限。若要符合最低特权原则，读取权限就足够了。

数据平面权限

通过工作区角色或项权限授予控制平面权限后，如果用户在数据平面级别仅具有读取权限，则还可以使用 T-SQL 命令授予用户 INSERT 和 ADMINISTER DATABASE BULK OPERATIONS 权限。

例如，以下 T-SQL 脚本通过使用其Microsoft Entra ID向单个用户授予这些权限。

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

GRANT INSERT to [mike@contoso.com];
GO

使用错误文件选项时，用户必须对存储帐户容器拥有Blob 存储参与者的最低权限。

使用 OneLake 作为源时，用户必须对源工作区（Lakehouse 所在的位置）和目标工作区（仓库所在的位置）具有参与者或更高权限。 Microsoft Entra ID和Fabric工作区角色控制所有访问权限。

Remarks

该 COPY 语句仅接受 UTF-8 和 UTF-16 的有效字符用于行数据和命令参数。如果使用包含无效字符的源文件或参数（如 ROWTERMINATOR 或 FIELDTERMINATOR），则 COPY 语句可能会错误地解释它们并导致意外结果，例如数据损坏或其他故障。在调用 COPY 该语句之前，请确保源文件和参数符合 UTF-8 或 UTF-16。

该 COPY INTO 语句对单个 varchar（max） 和 varbinary（max） 列的大小以及可以引入的总行大小有限制。

Parquet：最大 varchar（max）/varbinary（max） 列大小 16 MB，最大行大小为 1 GB。
CSV 和 JSONL：最大 varchar（max）/varbinary（max） 列大小 1 MB，最大行大小为 16 MB。

若要确保可靠的执行，请勿在操作过程中 COPY INTO 更改源文件和文件夹。

在命令运行时修改、删除或替换任何引用的文件或文件夹可能会导致作失败或导致数据引入不一致。
在执行 COPY INTO之前，请验证所有源数据是否稳定，并且在此过程中不会更改。

如果源数据精度高于目标列定义，则数值、日期和时间类型的值将被截断，而不是舍入。

OneLake 作为源的限制

仅支持Microsoft Entra ID 身份验证。 不允许使用其他身份验证方法，例如 SAS 令牌、共享密钥或连接字符串。
仓库项目 不支持作为源位置。文件必须源自通过 OneLake 存储公开文件的其他 Fabric 项。
OneLake 路径必须使用工作区和仓库 ID。 目前不支持工作区或 Lakehouses 的友好名称。
这两个工作区都需要参与者权限。 执行的用户必须在源 Lakehouse 工作区和目标 Warehouse 工作区上至少具有参与者角色。

Examples

有关在 Microsoft Fabric 中使用仓库的详细信息 COPY INTO ，请参阅使用 COPY 语句在 Microsoft Fabric 中引入数据仓库中的数据。

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'

Important

COPY 视 \n 为 \r\n 内在。有关详细信息，请参阅 ROWTERMINATOR 部分。
FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'

以下示例加载将换行符用作行终止符的文件，例如 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>'),
    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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. 加载 Parquet

此示例使用通配符通过执行用户的Entra ID加载文件夹下的所有 Parquet 文件。

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

E. 加载 JSONL

此示例使用通配符通过执行用户的Entra ID加载文件夹下的所有 JSONL 文件。

COPY INTO test_jsonl
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.jsonl'
WITH (
    FILE_TYPE = 'JSONL'
)

F. 将列名称映射到 JSONL 文档中的字段路径

以下示例显示了一个 JSON Lines （JSONL）文件，其中每行表示单个 JSON 对象：

{"CountryKey": 0, "CountryName": "ALGERIA", "RegionID": 0, "Population": 34800000}
{"CountryKey": 1, "CountryName": "ARGENTINA", "RegionID": 1, "Population": 46044703}
{"CountryKey": 2, "CountryName": "BRAZIL", "RegionID": 1, "Population": 203080756}

在中 COPY INTO，可以使用 JSON 路径表达式将表列映射到特定的 JSON 字段。此映射仅允许从源数据引入必填字段。

COPY INTO Countries (
  CountryID '$.CountryKey', 
  CountryName '$.CountryName', 
  RegionID '$.RegionKey', 
  Population '$.Population'
)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/countries.jsonl'
WITH (   
    FILE_TYPE = 'JSONL' 
)

G. 通过指定通配符和多个文件加载数据

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 = '|'
)

H. 从 OneLake 加载数据

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

反馈

此页面是否有帮助？

Last updated on 2026-05-04

COPY INTO （Transact-SQL）

Syntax

Arguments

schema_name

表名

（column_list）

外部地点

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

FILE_FORMAT = external_file_format_name

CREDENTIAL （IDENTITY = ''， SECRET = ''）

ERRORFILE = 目录位置

ERRORFILE_CREDENTIAL = （IDENTITY = ''， SECRET = ''）

MAXERRORS = max_errors

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

FIELDQUOTE = “field_quote”

FIELDTERMINATOR = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' |“UTF16”

IDENTITY_INSERT = “ON” |“OFF”

AUTO_CREATE_TABLE = { 'ON' |'OFF' }

Permissions

Remarks

Examples

A. 从公共存储帐户加载数据

B. 加载时通过共享访问签名 (SAS) 进行身份验证

C. 加载具有默认值的列列表时通过存储帐户密钥进行身份验证

D. 使用现有文件格式对象加载 Parquet 或 ORC

E. 加载时指定通配符和多个文件

F. 使用 MSI 凭据加载

G. 使用自动架构检测进行加载

FAQ

COPY 命令的性能与 PolyBase 有何比较？

加载压缩 CSV 文件时，COPY 命令的文件拆分指导是什么？

加载 Parquet 或 ORC 文件时，COPY 命令的文件拆分指导是什么？

文件的数量和大小有限制吗？

COPY 语句是否存在已知问题？

相关内容

Syntax

Arguments

warehouse_name

schema_name

表名

（column_list）

外部位置

FILE_TYPE = { 'CSV' |“JSONL” |'PARQUET' }

CREDENTIAL （IDENTITY = ''， SECRET = ''）

ERRORFILE = 目录位置

ERRORFILE_CREDENTIAL = （IDENTITY = ''， SECRET = ''）

MAXERRORS = max_errors

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

FIELDQUOTE = “field_quote”

FIELDTERMINATOR = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' |“UTF16”

PARSER_VERSION = { '1.0' |'2.0' }

MATCH_COLUMN_COUNT = { 'ON' |'OFF' }

将 COPY INTO 与 OneLake 配合使用

Permissions

控制平面权限

数据平面权限

Remarks

OneLake 作为源的限制

Examples

A. 从公共存储帐户加载数据

B. 加载时通过共享访问签名 (SAS) 进行身份验证

C. 加载具有默认值的列列表时通过存储帐户密钥 (SAK) 进行身份验证

D. 加载 Parquet

E. 加载 JSONL

F. 将列名称映射到 JSONL 文档中的字段路径

G. 通过指定通配符和多个文件加载数据

H. 从 OneLake 加载数据

相关内容

反馈

其他资源