Amazon Redshift
数据库开发人员指南 (API Version 2012-12-01)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

UNLOAD

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

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

语法

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

参数

('select-statement')

SELECT 查询。卸载查询的结果。大多数情况下,通过在查询中指定 ORDER BY 子句来按排序顺序卸载数据是值得的;这种方法将在重新加载数据时节省对数据排序所需的时间。

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

Copy
('select * from venue order by venueid')

注意

如果查询包含引号(例如括起文本值)或反斜杠 (\),则需要在查询文本中对其进行转义,如下所示:

Copy
('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>

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

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

重要

Amazon Redshift 将输出文件写入到的 Amazon S3 存储桶必须位于集群所在的区域中。

授权

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

MANIFEST

创建一个清单文件,其中明确列出由 UNLOAD 过程创建的数据文件。清单是一个 JSON 格式的文本文件,其中列出写入到 Amazon S3 的每个文件的 URL。清单文件将采用与卸载文件相同的 Amazon S3 路径前缀,按照 <object_path_prefix>manifest 的格式写入。例如,如果 UNLOAD 指定 Amazon S3 路径前缀“s3://mybucket/venue_”,则清单文件位置将为“s3://mybucket/venue_manifest”。

DELIMITER AS 'delimiter_character'

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

FIXEDWIDTH 'fixedwidth_spec'

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

Copy
'colID1:colWidth1,colID2:colWidth2, ...'
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 服务器端加密。

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

KMS_KEY_ID 'key-id'

用于在 Amazon S3 上加密数据文件的 AWS Key Management Service (AWS KMS) 密钥的密钥 ID。有关更多信息,请参阅《AWS 密钥管理服务开发人员指南》中的什么是 AWS 密钥管理服务? 如果指定 KMS_KEY_ID,您还必须指定 ENCRYPTED 参数。如果指定 KMS_KEY_ID,则不能使用 CREDENTIALS 参数进行身份验证,而应使用 IAM_ROLEACCESS_KEY_ID and 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 扩展名。

ADDQUOTES

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

Copy
"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 将创建以下三个文件。

Copy
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 的影响。

使用说明

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

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

重要

我们强烈建议您始终将 ESCAPE 与 UNLOAD 及 COPY 语句结合使用,除非您确定您的数据不包含任何分隔符或可能需要转义的其他字符。

丢失浮点精度

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

Limit 子句

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

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

请改为使用嵌套 LIMIT 子句。例如:

Copy
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 来填充表,然后从该表卸载。

本页内容: