UNLOAD - Amazon Redshift
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

UNLOAD

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

预设情况下,卸载文件的格式为管道符分隔 ( | ) 的文本。

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

现在,您可以将 Amazon Redshift 查询的结果卸载到 Apache Parquet 中的 Amazon S3 数据湖,Apache Parquet 是一种用于分析的高效开放列式存储格式。与文本格式相比,Parquet 格式的卸载速度提高了 2 倍,并且在 Amazon S3 中耗用的存储量减少了 6 倍。这使您能够以开放格式将在 Amazon S3 中完成的数据转换和数据扩充保存到 Amazon S3 数据湖中。然后,您可以使用 Redshift Spectrum 和其他 Amazon 服务(例如 Amazon Athena、Amazon EMR 和 SageMaker)分析您的数据。

Syntax

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

Parameters

('select-statement')

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

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

('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 前缀。如果使用 PARTITION BY,则会根据需要自动将正斜杠 (/) 添加到 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 集群不在同一个 Amazon 区域时,需要 REGION。

授权

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

[ FORMAT [AS] ] CSV | PARQUET

用于指定卸载格式以覆盖默认格式的关键词。

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

使用 PARQUET 时,卸载到 Apache Parquet 1.0 版本格式的文件。默认情况下,每个行组都使用 SNAPPY 压缩进行压缩。有关 Apache Parquet 格式的更多信息,请参阅 Parquet

关键字 FORMAT 和 AS 是可选的。您不能将 CSV 与 FIXEDWIDTH 一起使用。您不能将 PARQUET 与 DELIMITER、FIXEDWIDTH、ADDQUOTES、ESCAPE、NULL AS、HEADER、GZIP、BZIP2 或 ZSTD 一起使用。只有使用 Amazon Key Management Service 密钥的服务器端加密 (SSE-KMS) 支持带有 ENCRYPTED 的 PARQUET。

PARTITION BY ( column_name [, ... ] ) [INCLUDE]

指定卸载操作的分区键。UNLOAD 按照 Apache Hive 约定,根据分区键值自动将输出文件分区到分区文件夹中。例如,属于 2019 分区年和 9 月份的 Parquet 文件具有以下前缀:s3://my_bucket_name/my_prefix/year=2019/month=September/000.parquet

column_name 的值必须是正在卸载的查询结果中的列。

如果指定 PARTITION BY 与 INCLUDE 选项,则不会从卸载的文件中删除分区列。

Amazon Redshift 不支持 PARTITION BY 子句中的字符串文本。

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 一起使用。

DELIMITER AS 'delimiter_character'

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

FIXEDWIDTH 'fixedwidth_spec'

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

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

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

ENCRYPTED [AUTO] (加密 [自动])

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

对于 ENCRYPTED,您可能希望使用 Amazon 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 参数或 master_symmetric_key 凭证字符串的 CREDENTIALS 部分。如果使用主对称密钥卸载数据,请确保在对加密数据执行 COPY 操作时提供相同的密钥。

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

如果使用 ENCRYPTED AUTO,则 UNLOAD 命令将提取目标 Amazon S3 存储桶属性上的默认 Amazon KMS 加密密钥,并使用 Amazon KMS 密钥加密写入 Amazon S3 的文件。如果存储桶没有默认的 Amazon KMS 加密密钥,UNLOAD 会使用 Amazon 托管的加密密钥进行 Amazon Redshift 服务器端加密 (SSE-S3) 以自动创建加密文件。您不能将此选项与 KMS_KEY_ID、MASTER_SYMMETRIC_KEY 或包含 master_symmetric_key 的 CREDENTIALS 一起使用。

KMS_KEY_ID 'key-id'

指定用于在 Amazon S3 上加密数据文件的 Amazon Key Management Service (Amazon KMS) 密钥的密钥 ID。有关更多信息,请参阅什么是 Amazon Key Management Service? 如果指定 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 扩展名。

ZSTD

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

ADDQUOTES

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

"1","Hello, World"

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

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

NULL AS 'null-string'

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

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

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

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

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

  • 针对字符列报告错误

与用户定义的字符串表示 null 值的其他数据类型不同,Amazon Redshift 使用 JSON 格式导出 SUPER 数据列,并根据 JSON 格式将其表示为 null。因此,SUPER 数据列会忽略 UNLOAD 命令中使用的 NULL [AS] 选项。

ESCAPE

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

  • 换行:\n

  • 回车:\r

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

  • 转义字符:\

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

重要

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

ALLOWOVERWRITE

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

CLEANPATH

CLEANPATH 选项会删除位于 TO 子句中指定的 Amazon S3 路径中的现有文件,然后再将文件卸载到指定位置。

如果包含 PARTITION BY 子句,则只会从分区文件夹中删除现有文件,以接收 UNLOAD 操作生成的新文件。

您必须拥有 Amazon S3 存储桶的 s3:DeleteObject 权限。有关更多信息,请参阅 Amazon Simple Storage Service 控制台用户指南中的 Amazon S3 中的策略和权限。您使用 CLEANPATH 选项删除的文件将永久删除并且无法恢复。

如果您指定了 ALLOWOVERWRITE 选项,则无法指定 CLEANPATH 选项。

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 存储桶所在的 Amazon 区域。当 UNLOAD 的目标 Amazon S3 存储桶与 Amazon Redshift 集群不在同一个 Amazon 区域时,需要 REGION。

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

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

使用说明

将 ESCAPE 用于所有分隔的文本 UNLOAD 操作

在使用分隔符执行 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 来填充表,然后从该表卸载。

卸载 GEOMETRY 数据类型的列

您只能将 GEOMETRY 列卸载为文本或 CSV 格式。无法使用 FIXEDWIDTH 选项卸载 GEOMETRY 数据。以扩展的已知二进制 (EWKB) 格式的十六进制形式卸载数据。如果 EWKB 数据的大小大于 4 MB,则会出现警告,因为以后无法将数据加载到表中。

卸载 HLLSKETCH 数据类型

您只能将 HLLSKETCH 列卸载为文本或 CSV 格式。无法使用 FIXEDWIDTH 选项卸载 HLLSKETCH 数据。对于密集的 HyperLogLog 草图,数据将以 Base64 格式卸载,对于稀疏 HyperLogLog 草图,则以 JSON 格式卸载数据。有关更多信息,请参阅HyperLogLog 函数

以下示例将包含 HLLSKETCH 列的表导出到文件中。

CREATE TABLE a_table(an_int INT, b_int INT); INSERT INTO a_table VALUES (1,1), (2,1), (3,1), (4,1), (1,2), (2,2), (3,2), (4,2), (5,2), (6,2); CREATE TABLE hll_table (sketch HLLSKETCH); INSERT INTO hll_table select hll_create_sketch(an_int) from a_table group by b_int; UNLOAD ('select * from hll_table') TO 's3://mybucket/unload/' IAM_ROLE 'arn:aws:iam::0123456789012:role/MyRedshiftRole' NULL AS 'null' ALLOWOVERWRITE CSV;

FORMAT AS PARQUET 子句

使用 FORMAT AS PARQUET 时,请注意以下注意事项:

  • 卸载到 Parquet 不使用文件级压缩。每个行组都使用 SNAPPY 进行压缩。

  • 如果未指定 MAXFILESIZE,则默认最大文件大小为 6.2 GB。您可以使用 MAXFILESIZE 指定 5 MB–6.2 GB 的文件大小。写入文件时,实际文件大小是近似值,因此它可能不完全等于您指定的数字。

    要最大限度地提高扫描性能,Amazon Redshift 尝试创建包含相同大小的 32 MB 行组的 Parquet 文件。您指定的 MAXFILESIZE 值会自动向下舍入为 32 MB 的最接近倍数。例如,如果您指定 MAXFILESIZE 200 MB,则卸载的每个 Parquet 文件大约为 192 MB(32 MB 行组 x 6 = 192 MB)。

  • 如果列使用 TIMESTAMPTZ 数据格式,则只卸载时间戳值。未卸载时区信息。

  • 不要指定以下划线 (_) 或句点 (.) 字符开头的文件名前缀。Redshift Spectrum 将以这些字符开头的文件视为隐藏文件并忽略它们。

PARTITION BY 子句

使用 PARTITION BY 时,请注意以下注意事项:

  • 分区列不包含在输出文件中。

  • 请确保在 UNLOAD 语句中使用的 SELECT 查询中包含分区列。您可以在 UNLOAD 命令中指定任意数量的分区列。但有一个限制,即至少应有一个非分区列作为文件的一部分。

  • 如果分区键值为 null,Amazon Redshift 会自动将该数据卸载到名为 partition_column=__HIVE_DEFAULT_PARTITION__ 的默认分区中。

  • UNLOAD 命令不会对外部目录进行任何调用。要将新分区注册为现有外部表的一部分,请使用单独的 ALTER TABLE ... ADD PARTITION ... 命令。或者,您可以运行 CREATE EXTERNAL TABLE 命令将卸载的数据注册为新的外部表。也可以使用 Amazon Glue 爬网程序填充您的 Data Catalog。有关更多信息,请参阅 Amazon Glue 开发人员指南中的定义爬网程序

  • 如果使用 MANIFEST 选项,则 Amazon Redshift 在根 Amazon S3 文件夹中仅生成一个清单文件。

  • 可以用作分区键的列数据类型为:SMALLINT、INTEGER、BIGINT、DECIMAL、REAL、BOOLEAN、CHAR、VARCHAR、DATE 和 TIMESTAMP。

使用 ASSUMEROLE 权限授予对 UNLOAD 操作的 IAM 角色的访问权限

要为特定用户和组提供对 UNLOAD 操作的 IAM 角色的访问权限,超级用户可以向用户和组授予 IAM 角色的 ASSUMEROLE 权限。有关信息,请参阅 GRANT