Amazon Redshift
数据库开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

UNLOAD

使用 Amazon S3 服务器端加密 (SSE-S3) 功能将查询结果卸载到 Amazon S3 上的一个或多个文本文件中。您还可以指定利用 AWS Key Management Service 密钥进行服务器端加密 (SSE-KMS),或利用客户管理的密钥进行客户端加密 (CSE-CMK)。

您可以通过设置 MAXFILESIZE 参数来管理 Amazon S3 上文件的大小,并可通过扩展对文件数进行管理。

语法

UNLOAD ('select-statement') TO 's3://object-path/name-prefix' authorization [ option [ ... ] ] where option is { MANIFEST [ VERBOSE ] | HEADER | [ FORMAT [AS] ] CSV | DELIMITER [ AS ] 'delimiter-char' | FIXEDWIDTH [ AS ] 'fixedwidth-spec' } | ENCRYPTED | BZIP2 | GZIP | ZSTD | ADDQUOTES | NULL [ AS ] 'null-string' | ESCAPE | ALLOWOVERWRITE | PARALLEL [ { ON | TRUE } | { OFF | FALSE } ] | MAXFILESIZE [AS] max-size [ MB | GB ] ] | REGION [AS] 'aws-region'

参数

('select-statement')

SELECT 查询。卸载查询的结果。大多数情况下,通过在查询中指定 ORDER BY 子句来按排序顺序卸载数据是值得的。这种方法可以节省重新加载数据时对数据进行排序所需的时间。SELECT 子句中不支持 TOP。请改用 LIMIT。

必须用单引号将查询括起来,如下所示:

('select * from venue order by venueid')

注意

如果查询包含引号(例如,用引号将文本值引起来),则将文本放在两组单引号之间,并且还必须用单引号将查询引起来:

('select * from venue where venuestate=''NV''')
TO 's3://object-path/name-prefix'

Amazon S3 上的位置的完整路径(包括存储桶名称),Amazon Redshift 会将输出文件对象(如果指定 MANIFEST,则包括清单文件)写入到该位置。对象名将带有 name-prefix 前缀。为了增强安全性,UNLOAD 使用 HTTPS 连接来连接到 Amazon S3。默认情况下,UNLOAD 为每个切片写入一个或多个文件。UNLOAD 会将一个分片编号和一个分段编号附加到指定名称前缀,如下所示:

<object-path>/<name-prefix><slice-number>_part_<part-number>

如果指定了 MANIFEST,则会按以下格式写入清单文件:

<object_path>/<name_prefix>manifest

UNLOAD 会使用 Amazon S3 服务器端加密 (SSE) 自动创建加密文件,如果使用 MANIFEST,还将包括清单文件。COPY 命令在加载操作期间会自动读取服务器端加密文件。您可以使用 Amazon S3 管理控制台或 API 以透明方式从存储桶下载服务器端加密文件。有关更多信息,请转到使用服务器端加密保护数据

要使用 Amazon S3 客户端加密,请指定 ENCRYPTED 选项。

重要

当 Amazon S3 存储桶与 Amazon Redshift 集群不在同一个 AWS 区域时,需要 REGION。

授权

UNLOAD 命令需要向 Amazon S3 写入数据的授权。UNLOAD 命令的授权参数与 COPY 命令相同。有关更多信息,请参阅 COPY 命令语法参考中的 授权参数

MANIFEST [ VERBOSE ]

创建一个清单文件,其中明确列出由 UNLOAD 过程创建的数据文件的详细信息。清单是一个 JSON 格式的文本文件,其中列出写入到 Amazon S3 的每个文件的 URL。

如果使用 VERBOSE 选项指定 MANIFEST,则清单包含以下详细信息:

  • 列名和数据类型,对于 CHAR、VARCHAR 或 NUMERIC 数据类型,还包含每列的维度。对于 CHAR 和 VARCHAR 数据类型,维度是长度。对于 DECIMAL 或 NUMERIC 数据类型,维度是精度和小数位数。

  • 已卸载到每个文件的行计数。如果指定了 HEADER 选项,则行计数包括标题行。

  • 卸载的所有文件的总文件大小以及卸载到所有文件的总行数。如果指定了 HEADER 选项,则行计数包括标题行。

  • 作者。作者始终是“Amazon Redshift”。

您只能在 MANIFEST 之后指定 VERBOSE。

清单文件将采用与卸载文件相同的 Amazon S3 路径前缀,按照 <object_path_prefix>manifest 的格式写入。例如,如果 UNLOAD 指定 Amazon S3 路径前缀“s3://mybucket/venue_”,则清单文件位置为“s3://mybucket/venue_manifest”。

HEADER

在每个输出文件的顶部添加包含列名称的标题行。文本转换选项(如 CSV、DELIMITER、ADDQUOTES 和 ESCAPE)也适用于标题行。HEADER 不能与 FIXEDWIDTH 一起使用。

[ FORMAT [AS] ] CSV

使用逗号 (,) 字符作为分隔符卸载到 CSV 格式的文本文件。如果某个字段包含逗号、双引号、换行符或回车符,则卸载文件中的该字段会用双引号引起来。数据字段中的双引号字符通过一个额外的双引号字符进行转义。

关键字 FORMAT 和 AS 是可选的。CSV 不能与 DELIMITER 或 FIXEDWIDTH 一起使用。

DELIMITER AS 'delimiter_character'

用于在输出文件中分隔字段的单个 ASCII 字符,如管道字符 (|)、逗号 (,) 或制表符 (\t)。默认分隔符是竖线字符。AS 关键字是可选的。DELIMITER 不能与 FIXEDWIDTH 一起使用。如果数据包含分隔符,您需要指定 ESCAPE 选项来转义分隔符,或者使用 ADDQUOTES 用双引号将数据括起来。或者,指定一个数据中不包含的分隔符。

FIXEDWIDTH 'fixedwidth_spec'

将数据卸载到一个文件,其中每个列的宽度均为固定长度,而不是由分隔符隔开。fixedwidth_spec 是一个字符串,用于指定列数和列宽。AS 关键字是可选的。由于 FIXEDWIDTH 不会截断数据,因此 UNLOAD 语句中每个列的规格必须至少为该列的最长条目的长度。fixedwidth_spec 的格式如下:

'colID1:colWidth1,colID2:colWidth2, ...'

FIXEDWIDTH 不能与 DELIMITER 或 HEADER 一起使用。

ENCRYPTED

一个子句,指定 Amazon S3 上的输出文件的加密方法是 Amazon S3 服务器端加密还是客户端加密。如果指定了 MANIFEST,也会加密清单文件。有关更多信息,请参阅 卸载加密数据文件。如果不指定 ENCRYPTED 参数,UNLOAD 会使用 AWS 托管的加密密钥进行 Amazon S3 服务器端加密 (SSE-S3),自动创建加密文件。

要利用 AWS KMS 密钥进行服务器端加密 (SSE-KMS) 来卸载到 Amazon S3,请使用 KMS_KEY_ID 参数提供密钥 ID。CREDENTIALS 参数不能与 KMS_KEY_ID 参数配合使用。如果您使用 KMS_KEY_ID 来 UNLOAD 数据,则无需指定密钥即可 COPY 相同数据。

要利用客户提供的对称密钥进行客户端加密 (CSE-CMK) 来卸载到 Amazon S3,请使用 MASTER_SYMMETRIC_KEY 参数或 CREDENTIALS 凭证字符串的 master_symmetric_key 部分提供密钥。如果使用主对称密钥卸载数据,您必须提供与 COPY 加密数据相同的密钥。

UNLOAD 不支持使用客户提供的密钥 (SSE-C) 的 Amazon S3 服务器端加密。

要压缩加密的卸载文件,请添加 BZIP2、GZIP 或 ZSTD 参数。

KMS_KEY_ID 'key-id'

用于在 Amazon S3 上加密数据文件的 AWS Key Management Service (AWS KMS) 密钥的密钥 ID。有关更多信息,请参阅什么是 AWS Key Management Service? 如果指定 KMS_KEY_ID,您还必须指定 ENCRYPTED 参数。如果指定 KMS_KEY_ID,则不能使用 CREDENTIALS 参数进行身份验证,而应使用 IAM_ROLEACCESS_KEY_ID 和 SECRET_ACCESS_KEY

MASTER_SYMMETRIC_KEY 'master_key'

用于在 Amazon S3 上加密数据文件的主对称密钥。如果指定 MASTER_SYMMETRIC_KEY,您还必须指定 ENCRYPTED 参数。MASTER_SYMMETRIC_KEY 不能与 CREDENTIALS 参数配合使用。有关更多信息,请参阅从 Amazon S3 加载加密数据文件

BZIP2

对于每个切片,将数据卸载到一个或多个 bzip2 压缩的文件。将为每个生成的文件附加 .bz2 扩展名。

GZIP

对于每个切片,将数据卸载到一个或多个 gzip 压缩的文件。将为每个生成的文件附加 .gz 扩展名。

ZSTD

对于每个切片,将数据卸载到一个或多个 Zstandard 压缩的文件。将为每个生成的文件附加 .zst 扩展名。

ADDQUOTES

使用引号将每个卸载的数据字段括起来,以便 Amazon Redshift 能够自行卸载包含分隔符自身的数据值。例如,如果分隔符为逗号,则可以成功卸载并重新加载以下数据:

"1","Hello, World"

如果不添加引号,则将字符串 Hello, World 解析为两个单独的字段。

在使用 ADDQUOTES 的情况下,如果重新加载数据,则必须在 COPY 中指定 REMOVEQUOTES。

NULL AS 'null-string'

指定表示卸载文件中的 null 值的字符串。如果使用此选项,所有输出文件将包含指定字符串来替代在选定数据中找到的所有 null 值。如果未指定此选项,则 null 值将卸载为:

  • 零长度字符串(对于分隔的输出)

  • 空格字符串(对于固定宽度输出)

如果为固定宽度的卸载指定 null 字符串,并且输出列的宽度小于 null 字符串的宽度,则将发生以下行为:

  • 使用空字段作为非字符列的输出

  • 针对字符列报告错误

ESCAPE

对于分隔的卸载文件中的 CHAR 和 VARCHAR 列,将在每次出现的以下字符之前放置一个转义字符 (\):

  • 换行:\n

  • 回车:\r

  • 为卸载的数据指定的分隔符。

  • 转义字符:\

  • 引号字符:"'(如果在 UNLOAD 命令中同时指定 ESCAPE 和 ADDQUOTES)。

重要

如果已将 COPY 与 ESCAPE 选项结合使用来加载数据,则还必须在 UNLOAD 命令中指定 ESCAPE 选项以生成反向输出文件。同样,如果您使用 ESCAPE 选项执行 UNLOAD 命令,则在您对相同数据执行 COPY 操作时将需要使用 ESCAPE 选项。

ALLOWOVERWRITE

默认情况下,如果 UNLOAD 找到可能会覆盖的文件,则该命令将失败。如果指定 ALLOWOVERWRITE,则 UNLOAD 将覆盖现有文件(包括清单文件)。

PARALLEL

默认情况下,UNLOAD 根据集群中切片的数量将数据并行写入到多个文件。默认选项为 ON 或 TRUE。如果 PARALLEL 为 OFF 或 FALSE,UNLOAD 将按顺序写入到一个或多个数据文件,并完全根据 ORDER BY 子句(如果已使用)进行排序。数据文件的最大大小为 6.2 GB。例如,如果您卸载 13.4GB 数据,则 UNLOAD 将创建以下三个文件。

s3://mybucket/key000 6.2 GB s3://mybucket/key001 6.2 GB s3://mybucket/key002 1.0 GB

注意

UNLOAD 命令旨在使用并行处理。对于大多数情况,特别是文件将用于通过 COPY 命令加载表时,我们建议保留 PARALLEL 为启用状态。

MAXFILESIZE AS 最大大小 [ MB | GB ]

UNLOAD 在 Amazon S3 中创建的文件的最大大小。可以指定 5 MB 到 6.2 GB 之间的十进制值。AS 关键字是可选的。默认单位为 MB。如果未指定 MAXFILESIZE,则默认最大文件大小为 6.2 GB。清单文件的大小 (如果使用的话) 不受 MAXFILESIZE 的影响。

REGION [AS] 'aws-region'

目标 Amazon S3 存储桶所在的 AWS 区域。当 UNLOAD 的目标 Amazon S3 存储桶与 Amazon Redshift 集群不在同一个 AWS 区域时,需要 REGION。

aws_region 的值必须与 AWS 一般参考 中的 Amazon Redshift 区域和终端节点表中列出的 AWS 区域匹配。

默认情况下,UNLOAD 假定目标 Amazon S3 存储桶位于 Amazon Redshift 集群所在的 AWS 区域。

使用说明

对所有分隔的 UNLOAD 操作使用 ESCAPE

在使用分隔符执行 UNLOAD 时,您的数据可能包含该分隔符或 ESCAPE 选项描述中列出的任意字符。在这种情况下,必须将 ESCAPE 选项与 UNLOAD 语句一起使用。如果不将 ESCAPE 选项与 UNLOAD 结合使用,则使用卸载的数据执行的后续 COPY 操作可能会失败。

重要

我们强烈建议您始终将 ESCAPE 与 UNLOAD 和 COPY 语句一起使用。例外情况是您确定您的数据不包含任何分隔符或可能需要转义的其他字符。

丢失浮点精度

您可能遇到连续卸载并重新加载的浮点数据的精度丢失的情况。

Limit 子句

SELECT 查询无法在外部 SELECT 中使用 LIMIT 子句。例如,以下 UNLOAD 语句将失败。

unload ('select * from venue limit 10') to 's3://mybucket/venue_pipe_' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';

应改用嵌套的 LIMIT 子句,如下例所示。

unload ('select * from venue where venueid in (select venueid from venue order by venueid desc limit 10)') to 's3://mybucket/venue_pipe_' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';

或者,可以使用 LIMIT 子句通过 SELECT…INTO 或 CREATE TABLE AS 来填充表,然后从该表卸载。

本页内容: