COPY INTO <location>¶
将数据从表(或查询)卸载到以下位置之一的一个或多个文件中:
命名的内部暂存区(或表/用户暂存区)。然后,可以使用 GET 命令从该暂存区/位置下载这些文件。
引用外部位置(Amazon S3、Google Cloud Storage 或 Microsoft Azure)的命名外部暂存区。
外部位置(Amazon S3、Google Cloud Storage 或 Microsoft Azure)。
- 另请参阅:
语法¶
COPY INTO { internalStage | externalStage | externalLocation }
FROM { [<namespace>.]<table_name> | ( <query> ) }
[ PARTITION BY <expr> ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
TYPE = { CSV | JSON | PARQUET } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_ROWS ]
[ HEADER ]
其中:
internalStage ::= @[<namespace>.]<int_stage_name>[/<path>] | @[<namespace>.]%<table_name>[/<path>] | @~[/<path>]externalStage ::= @[<namespace>.]<ext_stage_name>[/<path>]externalLocation (for Amazon S3) ::= '<protocol>://<bucket>[/<path>]' [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( { { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } } ) } ] [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] | [ TYPE = 'NONE' ] ) ]externalLocation (for Google Cloud Storage) ::= 'gcs://<bucket>[/<path>]' [ STORAGE_INTEGRATION = <integration_name> ] [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]externalLocation (for Microsoft Azure) ::= 'azure://<account>.blob.core.windows.net/<container>[/<path>]' [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ] [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | 'NONE' } ] [ MASTER_KEY = '<string>' ] ) ]formatTypeOptions ::= -- If FILE_FORMAT = ( TYPE = CSV ... ) COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE RECORD_DELIMITER = '<string>' | NONE FIELD_DELIMITER = '<string>' | NONE FILE_EXTENSION = '<string>' ESCAPE = '<character>' | NONE ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE DATE_FORMAT = '<string>' | AUTO TIME_FORMAT = '<string>' | AUTO TIMESTAMP_FORMAT = '<string>' | AUTO BINARY_FORMAT = HEX | BASE64 | UTF8 FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE NULL_IF = ( '<string1>' [ , '<string2>' , ... ] ) EMPTY_FIELD_AS_NULL = TRUE | FALSE -- If FILE_FORMAT = ( TYPE = JSON ... ) COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE FILE_EXTENSION = '<string>' -- If FILE_FORMAT = ( TYPE = PARQUET ... ) COMPRESSION = AUTO | LZO | SNAPPY | NONE SNAPPY_COMPRESSION = TRUE | FALSEcopyOptions ::= OVERWRITE = TRUE | FALSE SINGLE = TRUE | FALSE MAX_FILE_SIZE = <num> INCLUDE_QUERY_ID = TRUE | FALSE DETAILED_OUTPUT = TRUE | FALSE
必填参数¶
INTO ...
指定在其中卸载数据文件的内部或外部位置:
@[namespace.]int_stage_name[/path]
文件将卸载到指定的命名内部暂存区。
@[namespace.]ext_stage_name[/path]
文件将卸载到指定的命名外部暂存区。
@[namespace.]%table_name[/path]
文件将卸载到指定表的暂存区。
@~[/path]
文件将卸载到当前用户的暂存区。
'protocol://bucket[/path]'
文件将卸载到指定的外部位置(S3 桶)。可能需要其他参数。有关详细信息,请参阅 其他云提供商参数 (本主题内容)。
'gcs://bucket[/path]'
文件将卸载到指定的外部位置(Google Cloud Storage 桶)。可能需要其他参数。有关详细信息,请参阅 其他云提供商参数 (本主题内容)。
'azure://account.blob.core.windows.net/container[/path]'
文件将卸载到指定的外部位置(Azure 容器)。可能需要其他参数。有关详细信息,请参阅 其他云提供商参数 (本主题内容)。
其中:
namespace
是内部或外部暂存区所在的数据库和/或架构,形式为database_name.schema_name
或schema_name
。如果数据库和架构当前正在用户会话中使用,则此参数为 选填;否则,为必填。protocol
是以下其中一项:s3
是指中国境外公共 AWS 区域的 S3 存储。s3china
代表中国境内公共 AWS 区域中的 S3 存储。s3gov
代表 政府区域 中的 S3 存储。
只能通过在同一政府区域中托管的 Snowflake 账户,使用存储集成访问 政府区域 中的云存储。
同样,如果您需要访问中国某个区域的云存储,则只能从中国同一区域托管的 Snowflake 账户访问存储集成。
在这些情况下,请在 CREATE STAGE 命令中使用 CREDENTIALS 参数(而不是使用存储集成)来提供身份验证凭据。
bucket
是桶的名称。
account
是 Azure 账户的名称(例如myaccount
)。将blob.core.windows.net
端点用于所有受支持类型的 Azure Blob 存储账户,包括 Data Lake Storage Gen2。请注意,目前只能通过在 Azure 同一政府区域中托管的 Snowflake 账户,使用存储集成访问 政府区域 中的 Azure Blob 存储。支持使用直接凭据从政府区域外部托管的账户访问 Blob 存储。
container
是 Azure 容器的名称(例如mycontainer
)。
选填的
path
参数指定包含卸载数据的文件的文件夹和文件名前缀。如果path
中未包含文件名前缀,或 如果指定了PARTITION BY
参数,则生成的数据文件的文件名会带有data_
前缀。相对路径修饰符(如
/./
和/../
)按字面解释,因为“路径”是名称的字面量前缀。例如:-- S3 bucket COPY INTO 's3://mybucket/./../a.csv' FROM mytable; -- Google Cloud Storage bucket COPY INTO 'gcs://mybucket/./../a.csv' FROM mytable; -- Azure container COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv' FROM mytable;
在这些 COPY 语句中,Snowflake 创建一个文件,该文件在存储位置中按字面含义命名为
./../a.csv
。
备注
如果内部或外部暂存区或路径名中包含特殊字符(包括空格),请将
INTO ...
字符串放在单引号内。INTO ...
值必须是字面量常量。该值不能是 SQL 变量。在 Snowflake Native App Framework 中写入外部暂存区时,必须使用
STAGE_URL
指定 URL 而不是外部后台文件名称和路径。
FROM ...
指定要卸载的数据的来源(可以是表或查询):
[namespace.]table_name
指定从中卸载数据的表的名称。
根据需要,可以在命名空间中以
database_name.schema_name
或schema_name
的形式指定表所在的数据库和/或架构。如果数据库和架构当前正在用户会话中使用,则此参数为 选填;否则,为必填。( query )
返回要卸载到文件中的数据的 SELECT 语句。可以通过在查询中指定 LIMIT / FETCH 子句来限制返回的行数。
备注
使用 CAST、:: 函数将列值类型转换为数据类型时,请验证该数据类型是否支持所有列值。对于指定的数据类型来说,太长的值可能会被截断。
其他云提供商参数¶
STORAGE_INTEGRATION = integration_name
或 .CREDENTIALS = ( cloud_specific_credentials )
:emph:` 当 COPY 语句指定外部存储 URI 而不是外部暂存区名称来作为目标云存储位置时,支持这两个参数。`指定安全凭据,这些凭据用于连接到云提供商,以及访问暂存了卸载文件的私有存储容器。
:emph:` 仅在卸载到外部私有云存储位置时才需要这两个参数;公有桶/容器不需要这两个参数 `
Amazon S3
STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息,请参阅 CREATE STORAGE INTEGRATION。
备注
Snowflake 建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。
CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] )
或 .CREDENTIALS = ( AWS_ROLE = 'string' )
指定安全凭据,这些凭据用于连接到 AWS,以及访问暂存了卸载文件的私有 S3 桶。有关更多信息,请参阅 配置对 Amazon S3 的安全访问。
您指定的凭证取决于您是否将桶的 Snowflake 访问权限与 AWS IAM (Identity & Access Management) 用户或角色关联:
IAM 用户: 需要临时 IAM 凭据。临时(又名“作用域”)凭据由 AWS Security Token Service (STS) 生成,由三个组件组成:
AWS_KEY_ID
AWS_SECRET_KEY
AWS_TOKEN
访问专用桶 需要 这三个组件。指定时间段后,临时凭证将过期,无法再使用。然后,您必须生成一组新的有效临时凭据。
重要
COPY 命令包含复杂的语法和敏感信息,如凭据。此外,这些命令会频繁执行,且通常存储在脚本或工作表中,这可能会导致敏感信息在无意中暴露。COPY 命令允许使用永久(也称为“长期”)凭据;但是,出于安全原因,请勿在 COPY 命令中使用 永久 凭据。请改用临时凭据。
如果必须使用永久凭据,请使用 外部暂存区,因其只需输入一次凭据即可进行安全存储,从而可以最大程度地减少暴露的可能性。
IAM 角色: 省略安全凭证和访问密钥,而是使用
AWS_ROLE
并指定 AWS 角色 ARN (Amazon Resource Name) 来标识角色。重要
使用 AWS IAM 角色访问私有 S3 桶以加载或卸载数据的功能现已弃用(即在未来版本中将删除支持,TBD)。Snowflake 建议修改使用此功能的任何现有 S3 暂存区,改为引用存储集成对象。有关说明,请参阅 选项 1:配置 Snowflake 存储集成以访问 Amazon S3。
Google Cloud Storage
STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息,请参阅 CREATE STORAGE INTEGRATION。
Microsoft Azure
STORAGE_INTEGRATION = integration_name
指定将外部云存储的身份验证责任委托给 Snowflake Identity and Access Management (IAM) 实体的存储集成的名称。有关更多详细信息,请参阅 CREATE STORAGE INTEGRATION。
备注
Snowflake 建议使用存储集成。此选项避免了在创建暂存或加载数据时使用 CREDENTIALS 参数提供云存储凭据的需要。
CREDENTIALS = ( AZURE_SAS_TOKEN = 'string' )
指定 SAS(共享访问签名)令牌,它们用于连接到 Azure,以及访问暂存了包含数据的文件的专用容器。凭据由 Azure 生成。
ENCRYPTION = ( cloud_specific_encryption )
用于临时 COPY 语句(不引用命名外部暂存区的语句)。仅在将数据卸载到加密存储位置中的文件时,才需要此参数
Amazon S3
ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] | [ TYPE = 'NONE' ] )
TYPE = ...
指定使用的加密类型。可能的值:
AWS_CSE
:客户端加密(需要一个MASTER_KEY
值)。目前,您提供的客户端 ` 主密钥 <https://csrc.nist.gov/glossary/term/master_key (https://csrc.nist.gov/glossary/term/master_key)>`_ 只能是对称密钥。请注意,当提供MASTER_KEY
值时,Snowflake 假定TYPE = AWS_CSE`(即,当提供 :samp:`MASTER_KEY
值时,不需要TYPE
)。AWS_SSE_S3
:不需要其他加密设置的服务器端加密。AWS_SSE_KMS
:接受可选的KMS_KEY_ID
值服务端加密。
有关加密类型的详细信息,请参阅 客户端加密 (http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html) 或 ` 服务器端加密 <http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html (http://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html)>`_ 的 AWS 文档。
NONE
:无加密。
MASTER_KEY = 'string'
(仅适用于AWS_CSE
加密)指定用于加密桶中文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。
KMS_KEY_ID = 'string'
(仅适用于AWS_SSE_KMS
加密)(可选)指定用于加密 卸载 到桶中的文件的 AWS KMS 托管密钥的 ID。如果未提供任何值,则默认 KMS 密钥 ID 用于在卸载时加密文件。
请注意,数据加载时会忽略此值。
Google Cloud Storage
ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = 'string' ] )
TYPE = ...
指定使用的加密类型。可能的值:
GCS_SSE_KMS
:接受可选的KMS_KEY_ID
值服务端加密。有关更多信息,请参阅 Google Cloud Platform 文档:
https://cloud.google.com/storage/docs/encryption/customer-managed-keys (https://cloud.google.com/storage/docs/encryption/customer-managed-keys)
https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys (https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys)
NONE
:无加密。
KMS_KEY_ID = 'string'
(仅适用于GCS_SSE_KMS
加密)(可选)指定用于加密 卸载 到桶中的文件的 Cloud KMS 托管密钥的 ID。如果未提供任何值,则桶中默认设置的 KMS 密钥 ID 用于在卸载时加密文件。
数据加载时会忽略此值。如果服务账户有足够的权限来解密桶中的数据,则加载操作应会成功。
Microsoft Azure
ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )
TYPE = ...
指定使用的加密类型。可能的值:
AZURE_CSE
:客户端加密(需要一个 MASTER_KEY 值)。有关信息,请参阅 Microsoft Azure 文档中的 ` 客户端加密信息 <https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption (https://docs.microsoft.com/en-us/azure/storage/common/storage-client-side-encryption)>`_。NONE
:无加密。
MASTER_KEY = 'string'
(仅适用于 AZURE_CSE 加密)指定用于加密文件的客户端主密钥。主密钥必须是 Base64 编码形式的 128 位或 256 位密钥。
可选参数¶
PARTITION BY expr
指定一个表达式,将卸载的表行分区到不同文件中。支持计算结果为字符串的任何 SQL 表达式。
卸载操作根据分区表达式拆分表行,并根据数据量和并行操作数确定要创建的文件数(分散到仓库内的计算资源中进行)。
文件名带有
data_
前缀,并包含分区列值。每个分区中的各个文件名都使用通用唯一标识符 (UUID) 进行标识。UUID 是用于卸载数据文件的 COPY 语句的查询 ID。小心
COPY INTO <location> 语句将分区列值写入卸载的文件名。对数据进行分区时,Snowflake 建议根据常见数据类型(如日期或时间戳)而不是可能敏感的字符串或整型值来进行。
请注意,文件 URLs 包含在 Snowflake 维护的内部日志中,以便在客户创建支持工单时帮助调试问题。因此,PARTITION BY 表达式引用的列中的数据也间接存储在内部日志中。这些日志可能会在部署区域之外进行处理。因此,最佳实践是在 PARTITION BY 表达式中仅包含日期、时间戳和布尔数据类型。
如果希望为您的账户禁用 COPY INTO <location> 语句中的 PARTITION BY 参数,请联系 ` Snowflake 支持部门 `_。
请注意,Snowflake 提供了一组参数来进一步限制数据卸载操作:
PREVENT_UNLOAD_TO_INLINE_URL 阻止对外部云存储位置执行临时数据卸载操作(即 COPY INTO <location> 语句直接在语句中指定云存储 URL 和访问设置)。
PREVENT_UNLOAD_TO_INTERNAL_STAGES 阻止对 任何 内部暂存区(包括用户暂存区、表暂存区或命名内部暂存区)执行数据卸载操作。
有关示例,请参阅 ` 将卸载的行分区到 Parquet 文件中 `_ (本主题内容)。
备注
不支持将以下复制选项值与 PARTITION BY 组合使用:
OVERWRITE = TRUE
SINGLE = TRUE
INCLUDE_QUERY_ID = FALSE
如果在与 PARTITION BY 组合使用的 SQL 语句中包含 ORDER BY 子句,并不能保证在卸载的文件中保留指定的顺序。
如果 PARTITION BY 表达式的计算结果为 NULL,则输出文件名中的分区路径为
_NULL_
(例如mystage/_NULL_/data_01234567-0123-1234-0000-000000001234_01_0_0.snappy.parquet
)。卸载到
PARQUET
类型的文件中时:由并行执行线程卸载的小型数据文件会自动合并到一个文件中,该文件的大小会尽可能接近 MAX_FILE_SIZE 复制选项值。
所有行组的大小均为 128 MB。行组是指将数据按逻辑横向分区到行中。不存在行组一定会具有的物理结构。行组由对应于数据集中每一列的列块组成。
卸载操作会尝试生成大小尽可能接近
MAX_FILE_SIZE
复制选项设置的文件。此复制选项的默认值为 16 MB。请注意,此行为仅在将数据卸载到 Parquet 文件时适用。VARIANT 列转换为简单的 JSON 字符串。对值进行类型转换,转换为数组(使用 TO_ARRAY 函数),生成一个 JSON 字符串数组。
未提供相关选项,以便从卸载的数据文件中省略分区表达式内的列。
FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' )
或 .FILE_FORMAT = ( TYPE = CSV | JSON | PARQUET [ ... ] )
指定包含卸载数据的数据文件的格式:
FORMAT_NAME = 'file_format_name'
指定用于从表中卸载数据的现有命名文件格式。命名文件格式决定数据文件的格式类型(CSV、JSON、PARQUET)以及其他任何格式选项。有关更多信息,请参阅 CREATE FILE FORMAT。
TYPE = CSV | JSON | PARQUET [ ... ]
指定从表中卸载的文件的类型。
如果指定了格式类型,则可以指定其他特定于格式的选项。有关更多详细信息,请参阅 :ref:`格式类型选项 <label-copy_into_location_formattypeoptions>`(本主题内容)。
备注
JSON 只能用于从 VARIANT 类型的列(即包含 JSON 数据的列)中卸载数据。
目前,无法以 Parquet 格式成功卸载 VARIANT 列中的嵌套数据。
copyOptions
指定卸载数据的一个或多个复制选项。有关更多详细信息,请参阅 复制选项 (本主题内容)。
VALIDATION_MODE = RETURN_ROWS
字符串(常量),指示 COPY 命令返回 SQL 语句中的查询结果,而不是 将结果卸载到指定的云存储位置。唯一支持的验证选项是
RETURN_ROWS
。此选项返回查询生成的所有行。验证查询后,可以移除
VALIDATION_MODE
以执行卸载操作。HEADER = TRUE | FALSE
指定是否在输出文件中包含表列标题。
将此选项设置为
TRUE
会在输出文件中包含表列标题。请注意,如果 COPY 操作将数据卸载到多个文件,则列标题将包含在 每个 文件中。
以 Parquet 格式卸载数据时,表列名称将保留在输出文件中。
将此选项设置为
FALSE
可指定以下行为:- CSV:
不要在输出文件中包含表列标题。
- Parquet:
在输出文件中包含通用列标题(例如
col1
、col2
等)。
默认:
FALSE
格式类型选项 (formatTypeOptions
)¶
根据指定的文件格式类型 (FILE_FORMAT = ( TYPE = ... )
),可以包含以下一个或多个特定于格式的选项(用空格、逗号或换行符分隔):
TYPE = CSV¶
COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
字符串(常量),指定使用给定的压缩算法压缩卸载的数据文件。
支持的值
备注
AUTO
卸载的文件使用默认算法 gzip 自动压缩。
GZIP
BZ2
BROTLI
加载 Brotli 压缩文件时必须进行指定。
ZSTD
支持 Zstandard v0.8(及更高版本)。
DEFLATE
卸载的文件使用 Deflate(带 zlib 标头,RFC1950)进行压缩。
RAW_DEFLATE
卸载的文件使用 Raw Deflate(不带标头,RFC1951)进行压缩。
NONE
卸载的文件不会被压缩。
默认:
AUTO
RECORD_DELIMITER = 'string' | NONE
一个或多个单字节或多字节字符,用于分隔卸载文件中的记录。接受常见的转义序列或以下单字节或多字节字符:
- 单字节字符:
八进制值(以
\\
为前缀)或十六进制值(以0x
或\x
为前缀)。例如,对于由重音符号 (^
) 字符分隔的记录,请指定八进制 (\\136
) 或十六进制 (0x5e
) 值。- 多字节字符:
十六进制值(前缀为
\x
)。例如,对于由分 (¢
) 字符分隔的记录,请指定十六进制 (\xC2\xA2
) 值。RECORD_DELIMITER 或 FIELD_DELIMITER 分隔符不能是其他文件格式选项(例如
FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'
)的分隔符的子字符串。
指定的分隔符必须是有效的 UTF-8 字符,而不是随机的字节序列。另请注意,分隔符限制为最多 20 个字符。
也接受
NONE
的值。默认值:换行符。请注意,“换行符”是合乎逻辑的,因而
\r\n
可以理解为 Windows 平台上文件的换行符。FIELD_DELIMITER = 'string' | NONE
一个或多个单字节或多字节字符,用于分隔卸载文件中的字段。接受常见的转义序列或以下单字节或多字节字符:
- 单字节字符:
八进制值(以
\\
为前缀)或十六进制值(以0x
或\x
为前缀)。例如,对于由重音符号 (^
) 字符分隔的记录,请指定八进制 (\\136
) 或十六进制 (0x5e
) 值。- 多字节字符:
十六进制值(前缀为
\x
)。例如,对于由分 (¢
) 字符分隔的记录,请指定十六进制 (\xC2\xA2
) 值。RECORD_DELIMITER 或 FIELD_DELIMITER 分隔符不能是其他文件格式选项(例如
FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb'
)的分隔符的子字符串。备注
对于非 ASCII 字符,必须使用十六进制字节序列值来获取确定性行为。
指定的分隔符必须是有效的 UTF-8 字符,而不是随机的字节序列。另请注意,分隔符限制为最多 20 个字符。
也接受
NONE
的值。默认值:逗号 (
,
)
FILE_EXTENSION = 'string' | NONE
此字符串指定卸载到暂存区的文件的扩展名。接受任何扩展名。用户负责指定可由所需软件或服务读取的有效文件扩展名。
备注
如果
SINGLE
复制选项为TRUE
,则默认情况下,COPY 命令会卸载没有文件扩展名的文件。要指定文件扩展名,请在internal_location
或external_location
路径中提供文件名和扩展名。例如:copy into @stage/data.csv ...
默认值为 null,表示文件扩展名由格式类型确定,例如
.csv[compression]
,其中compression
是由压缩方法添加的扩展名(如果已设置COMPRESSION
)。DATE_FORMAT = 'string' | AUTO
此字符串定义卸载数据文件中的日期值格式。如果未指定值或设置为
AUTO
,则使用 DATE_OUTPUT_FORMAT 参数的值。默认:
AUTO
TIME_FORMAT = 'string' | AUTO
此字符串定义卸载数据文件中的时间值格式。如果未指定值或设置为
AUTO
,则使用 TIME_OUTPUT_FORMAT 参数的值。默认:
AUTO
TIMESTAMP_FORMAT = 'string' | AUTO
此字符串定义卸载数据文件中的时间戳值格式。如果未指定值或设置为
AUTO
,则使用 TIMESTAMP_OUTPUT_FORMAT 参数的值。默认:
AUTO
BINARY_FORMAT = HEX | BASE64 | UTF8
字符串(常量),用于定义二进制输出的编码格式。从表中的二进制列卸载数据时可以使用该选项。
默认:
HEX
ESCAPE = 'character' | NONE
- 使用:
数据加载和卸载
- 定义:
用作封闭或未封闭字段值的转义字符的单字节字符串。转义字符对字符序列中的后续字符调用替代解释。您可以使用 ESCAPE 字符将数据中
FIELD_OPTIONALLY_ENCLOSED_BY
字符的实例解释为字面量。转义字符还可用于对数据中自身的实例进行转义。
接受常见的转义序列、八进制值或十六进制值。
通过设置
FIELD_OPTIONALLY_ENCLOSED_BY
指定用于包围字段的字符。如果设置此选项,它将替换
ESCAPE_UNENCLOSED_FIELD
的转义字符集。- 默认值:
NONE
ESCAPE_UNENCLOSED_FIELD = 'character' | NONE
- 使用:
数据加载和卸载
- 定义:
仅用作未封闭字段值的转义字符的单字节字符串。转义字符对字符序列中的后续字符调用替代解释。您可以使用 ESCAPE 字符将数据中
FIELD_DELIMITER
或RECORD_DELIMITER
字符的实例解释为字面量。转义字符还可用于对数据中自身的实例进行转义。
接受常见的转义序列、八进制值或十六进制值。
如果设置了
ESCAPE
,该文件格式选项的转义字符集将替换此选项。- 默认值:
反斜杠 (
\\
)
FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE
用于包围字符串的字符。值可以是
NONE
、单引号字符 ('
) 或双引号字符 ("
)。要使用单引号字符,请使用八进制或十六进制表示形式 (0x27
) 或双单引号转义 (''
)。源表中的字段包含此字符时,Snowflake 使用相同的字符对其进行转义以进行卸载。例如,如果值是双引号字符,且字段包含字符串
A "B" C
,则 Snowflake 会按如下方式对双引号进行转义以进行卸载:A ""B"" C
默认:
NONE
NULL_IF = ( 'string1' [ , 'string2' ... ] )
用于从 SQL NULL 进行转换的字符串。Snowflake 会将 SQL NULL 值转换为列表中的第一个值。
默认:
\N
(即 NULL,假设ESCAPE_UNENCLOSED_FIELD=\
)EMPTY_FIELD_AS_NULL = TRUE | FALSE
与
FIELD_OPTIONALLY_ENCLOSED_BY
结合使用。FIELD_OPTIONALLY_ENCLOSED_BY = NONE
时,设置EMPTY_FIELD_AS_NULL = FALSE
指定将表中的空字符串卸载为空字符串值,而不用将字段值放在引号内。如果设置为
TRUE
,FIELD_OPTIONALLY_ENCLOSED_BY
必须指定一个字符来包围字符串。默认:
TRUE
TYPE = JSON¶
COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
字符串(常量)。使用指定的压缩算法压缩数据文件。
支持的值
备注
AUTO
卸载的文件使用默认算法 gzip 自动压缩。
GZIP
BZ2
BROTLI
ZSTD
DEFLATE
卸载的文件使用 Deflate(带 zlib 标头,RFC1950)进行压缩。
RAW_DEFLATE
卸载的文件使用 Raw Deflate(不带标头,RFC1951)进行压缩。
NONE
卸载的文件不会被压缩。
默认:
AUTO
FILE_EXTENSION = 'string' | NONE
此字符串指定卸载到暂存区的文件的扩展名。接受任何扩展名。用户负责指定可由所需软件或服务读取的有效文件扩展名。
默认值为 null,表示文件扩展名由格式类型确定,例如
.csv[compression]
,其中compression
是由压缩方法添加的扩展名(如果已设置COMPRESSION
)。
TYPE = PARQUET¶
COMPRESSION = AUTO | LZO | SNAPPY | NONE
字符串(常量)。使用指定的压缩算法压缩数据文件。
支持的值
备注
AUTO
文件使用 Snappy(默认压缩算法)进行压缩。
LZO
默认情况下使用 Snappy 算法压缩文件。如果改为应用 Lempel-Ziv-Oberhumer (LZO) 压缩算法,请指定此值。
SNAPPY
默认情况下使用 Snappy 算法压缩文件。您可以选择指定此值。
NONE
指定不压缩卸载的文件。
默认:
AUTO
SNAPPY_COMPRESSION = TRUE | FALSE
此布尔值指定是否使用 SNAPPY 算法压缩卸载的文件。
备注
已弃用。`请改用 :samp:`COMPRESSION = SNAPPY。
默认:
TRUE
复制选项 (copyOptions
)¶
您可以指定以下一个或多个复制选项(用空格、逗号或换行符分隔):
OVERWRITE = TRUE | FALSE
- 定义:
如果文件的存储位置中存在具有匹配名称的文件,此布尔值指定 COPY 命令是否覆盖这些文件。如果现有文件与 COPY 命令卸载的文件的名称不匹配,该选项 不会 移除任何这些文件。
在多次执行同一个 COPY INTO <location> 语句的情况下,启用该选项常常有助于防止目标暂存区中出现数据重复。但是,当卸载操作将多个文件写入一个暂存区时,Snowflake 会追加后缀,以确保每个文件名在并行执行线程中是唯一的(例如
data_0_1_0
)。并行执行线程数可能因卸载操作而异。如果卸载操作写入的文件在文件名上与上一个操作写入的文件不同,包含此复制选项的 SQL 语句将无法替换现有文件,从而导致文件重复。此外,在计算机或网络发生故障的极少数情况下,会重新尝试执行卸载作业。在这种情况下,卸载操作不会先移除之前通过第一次尝试写入的任何文件,而是会将其他文件写入暂存区。
为避免目标暂存区中出现数据重复,我们建议设置
INCLUDE_QUERY_ID = TRUE
复制选项而不是OVERWRITE = TRUE
,并且在每个卸载作业之间移除目标暂存区和路径中的所有数据文件(或对每个卸载操作使用不同的路径)。- 默认值:
FALSE
SINGLE = TRUE | FALSE
- 定义:
此布尔值指定是生成单个文件还是多个文件。如果为
FALSE
,则path
中必须包含文件名前缀。
重要
如果为
SINGLE = TRUE
,则 COPY 会忽略FILE_EXTENSION
文件格式选项,并输出一个名为 data 的文件。要指定文件扩展名,请在内部或外部位置path
中提供文件名和扩展名。例如:COPY INTO @mystage/data.csv ...
此外,如果
COMPRESSION
文件格式选项也显式设置为支持的压缩算法之一(例如GZIP
),则指定的内部或外部位置path
必须以具有相应文件扩展名(例如gz
)的文件名结尾,以便可以使用适当的工具解压缩文件。例如:COPY INTO @mystage/data.gz ... COPY INTO @mystage/data.csv.gz ...
- 默认值:
FALSE
MAX_FILE_SIZE = num
- 定义:
大于 0 的数字,指定每个线程并行生成的每个文件的大小上限(以字节为单位)。请注意,实际文件大小和卸载的文件数由数据总量和可用于并行处理的节点数决定。
Snowflake 利用并行执行来优化性能。线程数无法修改。
最大值:5 GB(Amazon S3、Google Cloud Storage 或 Microsoft Azure 暂存区)
备注
COPY 命令一次卸载一组表行。如果设置一个非常小的
MAX_FILE_SIZE
值(例如,小于 1 MB),则一组行中的数据量可能会超过指定的大小。- 默认值:
16777216
(16 MB)
INCLUDE_QUERY_ID = TRUE | FALSE
- 定义:
布尔值,指定是否通过在卸载数据文件的文件名中包含通用唯一标识符 (UUID) 来唯一标识卸载的文件。此选项有助于确保并发的 COPY 语句不会意外覆盖卸载的文件。
- 值:
如果为
TRUE
,则将 UUID 添加到卸载文件的名称中。UUID 是用于卸载数据文件的 COPY 语句的查询 ID。UUID 是文件名的一部分:<path>/data_<uuid>_<name>.<extension>
。如果发生内部重试,此选项还可以防止卸载重复数据。内部重试发生时,Snowflake 会删除部分已卸载文件集(由 UUID 标识),然后重新启动复制操作。如果为
FALSE
,则不会将 UUID 添加到卸载的数据文件中。备注
将卸载的表行分区到不同文件中时(通过在 COPY INTO <location> 语句中设置
PARTITION BY expr
),INCLUDE_QUERY_ID = TRUE
是默认的复制选项值。此值不能更改为 FALSE。如果设置了以下任一复制选项,则 不 支持
INCLUDE_QUERY_ID = TRUE
:SINGLE = TRUE
OVERWRITE = TRUE
在计算机或网络发生故障的极少数情况下,会重新尝试执行卸载作业。在这种情况下,卸载操作会移除已写入暂存区的任何相关文件(其 UUID 为当前查询的 ID),然后重新尝试卸载数据。写入暂存区的任何新文件都会将重试的查询 ID 用作 UUID。
- 默认值:
FALSE
DETAILED_OUTPUT = TRUE | FALSE
- 定义:
布尔值,指定命令输出是应描述卸载操作还是因该操作而卸载的各个文件。
- 值:
如果为
TRUE
,则每个卸载到指定暂存区的文件都会在命令输出中占据一行。相应的列显示每个文件的路径和名称、其大小以及卸载到文件的行数。如果为
FALSE
,则命令输出只包含一行(描述了整个卸载操作)。相应的列显示从表中卸载的数据总量、压缩前后的大小(如果适用)和卸载的总行数。
- 默认值:
FALSE
使用说明¶
仅当您直接卸载到私有存储位置(Amazon S3、Google Cloud Storage 或 Microsoft Azure)时,
STORAGE_INTEGRATION
或CREDENTIALS
才适用。如果卸载到公有桶,则不需要安全访问;如果卸载到命名的外部暂存区,则该暂存区将提供访问桶所需的所有凭据信息。如果在当前命名空间中引用文件格式,则可以省略格式标识符两边的单引号。
仅在从表中的 VARIANT 列卸载数据时,才能将
JSON
指定为TYPE
。卸载到
CSV
、JSON
或PARQUET
类型的文件中时:默认情况下,VARIANT 列在输出文件中转换为简单的 JSON 字符串。
卸载到
PARQUET
类型的文件中时:卸载 TIMESTAMP_TZ 或 TIMESTAMP_LTZ 数据会产生错误。
如果源表包含 0 行,则 COPY 操作 不会 卸载数据文件。
当卸载到非空存储位置时,此 SQL 命令不会返回警告。为避免数据管道使用存储位置中的文件时出现意外行为,Snowflake 建议仅写入空存储位置。
失败的卸载操作仍可能导致卸载数据文件;例如,如果语句超出其超时限制并被取消。此外,如果对另一个区域中的云存储执行卸载操作,即使操作失败,也会产生数据传输成本。
如果在列上设置了 掩码策略,则掩码策略将应用于数据,从而导致未经授权的用户在列中看到掩码的数据。
要查看此命令的执行状态和历史记录,请使用 QUERY_HISTORY 视图。
要了解更多信息,请参阅 将数值列显式转换为 Parquet 数据类型。
示例¶
将数据从表卸载到表暂存区中的文件¶
使用文件夹/文件名前缀 (result/data_
)、命名文件格式 (myformat
) 和 gzip 压缩算法,将数据从 orderstiny
表中卸载到表的暂存区:
COPY INTO @%orderstiny/result/data_ FROM orderstiny FILE_FORMAT = (FORMAT_NAME ='myformat' COMPRESSION='GZIP');
将数据从查询卸载到命名内部暂存区中的文件¶
使用文件夹/文件名前缀 (result/data_
)、命名文件格式 (myformat
) 和 gzip 压缩算法,将查询结果卸载到命名的内部暂存区 (my_stage
):
COPY INTO @my_stage/result/data_ FROM (SELECT * FROM orderstiny) file_format=(format_name='myformat' compression='gzip');请注意,上面的示例在功能上与第一个示例等效,只不过包含卸载数据的文件存储在
my_stage
的暂存区位置而不是orderstiny
的表位置。
将数据从表直接卸载到外部位置的文件¶
使用命名的 my_csv_format
文件格式将表中的所有数据卸载到存储位置:
Amazon S3
使用名为
myint
的引用存储集成来访问引用的 S3 桶:COPY INTO 's3://mybucket/unload/' FROM mytable STORAGE_INTEGRATION = myint FILE_FORMAT = (FORMAT_NAME = my_csv_format);使用提供的凭据来访问引用的 S3 桶:
COPY INTO 's3://mybucket/unload/' FROM mytable CREDENTIALS = (AWS_KEY_ID='xxxx' AWS_SECRET_KEY='xxxxx' AWS_TOKEN='xxxxxx') FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Google Cloud Storage
使用名为
myint
的引用存储集成来访问引用的 GCS 桶:COPY INTO 'gcs://mybucket/unload/' FROM mytable STORAGE_INTEGRATION = myint FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Microsoft Azure
使用名为
myint
的引用存储集成来访问引用的容器:COPY INTO 'azure://myaccount.blob.core.windows.net/unload/' FROM mytable STORAGE_INTEGRATION = myint FILE_FORMAT = (FORMAT_NAME = my_csv_format);使用提供的凭据来访问引用的容器:
COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/unload/' FROM mytable CREDENTIALS=(AZURE_SAS_TOKEN='xxxx') FILE_FORMAT = (FORMAT_NAME = my_csv_format);
将卸载的行分区到 Parquet 文件中¶
以下示例按两列中的值将卸载的行分区到 Parquet 文件中:日期列和时间列。该示例指定每个卸载文件的最大大小:
CREATE or replace TABLE t1 (
dt date,
ts time
)
AS
SELECT TO_DATE($1)
,TO_TIME($2)
FROM VALUES
('2020-01-28', '18:05')
,('2020-01-28', '22:57')
,('2020-01-28', NULL)
,('2020-01-29', '02:15')
;
SELECT * FROM t1;
+------------+----------+
| DT | TS |
|------------+----------|
| 2020-01-28 | 18:05:00 |
| 2020-01-28 | 22:57:00 |
| 2020-01-28 | 22:32:00 |
| 2020-01-29 | 02:15:00 |
+------------+----------+
-- Partition the unloaded data by date and hour. Set ``32000000`` (32 MB) as the upper size limit of each file to be generated in parallel per thread.
COPY INTO @%t1
FROM t1
PARTITION BY ('date=' || to_varchar(dt, 'YYYY-MM-DD') || '/hour=' || to_varchar(date_part(hour, ts))) -- Concatenate labels and column values to output meaningful filenames
FILE_FORMAT = (TYPE=parquet)
MAX_FILE_SIZE = 32000000
HEADER=true;
LIST @%t1;
+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+
| name | size | md5 | last_modified |
|------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------|
| __NULL__/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet | 512 | 1c9cb460d59903005ee0758d42511669 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=18/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet | 592 | d3c6985ebb36df1f693b52c4a3241cc4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=22/data_019c059d-0502-d90c-0000-438300ad6596_006_6_0.snappy.parquet | 592 | a7ea4dc1a8d189aabf1768ed006f7fb4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-29/hour=2/data_019c059d-0502-d90c-0000-438300ad6596_006_0_0.snappy.parquet | 592 | 2d40ccbb0d8224991a16195e2e7e5a95 | Wed, 5 Aug 2020 16:58:16 GMT |
+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+
在卸载的文件中保留 NULL/空字段数据¶
在卸载的文件中保留 SQL NULL 和空字段:
-- View the table column values SELECT * FROM HOME_SALES; +------------+-------+-------+-------------+--------+------------+ | CITY | STATE | ZIP | TYPE | PRICE | SALE_DATE | |------------+-------+-------+-------------+--------+------------| | Lexington | MA | 95815 | Residential | 268880 | 2017-03-28 | | Belmont | MA | 95815 | Residential | | 2017-02-21 | | Winchester | MA | NULL | Residential | | 2017-01-31 | +------------+-------+-------+-------------+--------+------------+ -- Unload the table data into the current user's personal stage. The file format options retain both the NULL value and the empty values in the output file COPY INTO @~ FROM HOME_SALES FILE_FORMAT = (TYPE = csv NULL_IF = ('NULL', 'null') EMPTY_FIELD_AS_NULL = false); -- Contents of the output file Lexington,MA,95815,Residential,268880,2017-03-28 Belmont,MA,95815,Residential,,2017-02-21 Winchester,MA,NULL,Residential,,2017-01-31
将数据卸载到单个文件¶
使用 SINGLE 复制选项将所有行卸载到单个数据文件:
copy into @~ from HOME_SALES single = true;
在卸载文件的名称中包含 UUID¶
通过将 INCLUDE_QUERY_ID 复制选项设置为 TRUE,在卸载文件的名称中包含 UUID:
-- Unload rows from the T1 table into the T1 table stage:
COPY INTO @%t1
FROM t1
FILE_FORMAT=(TYPE=parquet)
INCLUDE_QUERY_ID=true;
-- Retrieve the query ID for the COPY INTO location statement.
-- This optional step enables you to see that the query ID for the COPY INTO location statement
-- is identical to the UUID in the unloaded files.
SELECT last_query_id();
+--------------------------------------+
| LAST_QUERY_ID() |
|--------------------------------------|
| 019260c2-00c0-f2f2-0000-4383001cf046 |
+--------------------------------------+
LS @%t1;
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+
| name | size | md5 | last_modified |
|----------------------------------------------------------------+------+----------------------------------+-------------------------------|
| data_019260c2-00c0-f2f2-0000-4383001cf046_0_0_0.snappy.parquet | 544 | eb2215ec3ccce61ffa3f5121918d602e | Thu, 20 Feb 2020 16:02:17 GMT |
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+
验证要卸载的数据(从查询中)¶
在验证模式下执行 COPY 以返回查询结果,然后查看将从 orderstiny
表中卸载的数据(如果在正常模式下执行 COPY):
COPY INTO @my_stage FROM (SELECT * FROM orderstiny LIMIT 5) VALIDATION_MODE='RETURN_ROWS'; ----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+ C1 | C2 | C3 | C4 | C5 | C6 | C7 | C8 | C9 | ----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+ 1 | 36901 | O | 173665.47 | 1996-01-02 | 5-LOW | Clerk#000000951 | 0 | nstructions sleep furiously among | 2 | 78002 | O | 46929.18 | 1996-12-01 | 1-URGENT | Clerk#000000880 | 0 | foxes. pending accounts at the pending\, silent asymptot | 3 | 123314 | F | 193846.25 | 1993-10-14 | 5-LOW | Clerk#000000955 | 0 | sly final accounts boost. carefully regular ideas cajole carefully. depos | 4 | 136777 | O | 32151.78 | 1995-10-11 | 5-LOW | Clerk#000000124 | 0 | sits. slyly regular warthogs cajole. regular\, regular theodolites acro | 5 | 44485 | F | 144659.20 | 1994-07-30 | 5-LOW | Clerk#000000925 | 0 | quickly. bold deposits sleep slyly. packages use slyly | ----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+