从 Amazon S3 执行 COPY 操作
要从位于一个或多个 S3 桶中的文件加载数据,请使用 FROM 子句指示 COPY 在 Amazon S3 中查找文件的方式。您可以提供数据文件的对象路径作为 FROM 子句的一部分,也可以提供包含了 Amazon S3 对象路径列表的清单文件的位置。从 Amazon S3 执行 COPY 操作将使用 HTTPS 连接。确保将 S3 IP 范围添加到您的允许列表中。要了解有关所需 S3 IP 范围的更多信息,请参阅网络隔离。
重要
如果包含数据文件的 Amazon S3 桶未驻留在您的集群所在的 Amazon 区域内,则必须使用 REGION 参数指定数据所在的区域。
语法
FROM { 's3://objectpath' | 's3://manifest_file' } authorization | MANIFEST | ENCRYPTED | REGION [AS] 'aws-region' | optional-parameters
示例
以下示例使用对象路径从 Amazon S3 加载数据。
copy customer from 's3://amzn-s3-demo-bucket/customer' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
以下示例使用清单文件从 Amazon S3 加载数据。
copy customer from 's3://amzn-s3-demo-bucket/cust.manifest' iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole' manifest;
参数
- FROM
-
要加载的数据的源。有关 Amazon S3 文件编码的更多信息,请参阅数据转换参数。
- 's3://copy_from_s3_objectpath'
-
指定包含数据的 Amazon S3 对象的路径,例如
's3://amzn-s3-demo-bucket/custdata.txt'
。s3://copy_from_s3_objectpath 参数可引用单个文件或者具有相同键前缀的一组对象或文件夹。例如,名称custdata.txt
是引用很多物理文件(custdata.txt
、custdata.txt.1
,等等)的键前缀。custdata.txt.2
custdata.txt.bak
键前缀还可以引用很多文件夹。例如,'s3://amzn-s3-demo-bucket/custfolder'
引用文件夹custfolder
、custfolder_1
,等等。custfolder_2
如果键前缀引用多个文件夹,则加载这些文件夹中的所有文件。如果键前缀与一个文件以及一个文件夹匹配,如custfolder.log
,COPY 还将尝试加载该文件。如果键前缀可能导致 COPY 尝试加载不需要的文件,请使用清单文件。有关更多信息,请参阅以下内容:copy_from_s3_manifest_file。重要
如果包含数据文件的 S3 桶未驻留在您的集群所在的 Amazon 区域内,则必须使用 REGION 参数指定数据所在的区域。
有关更多信息,请参阅 从 Amazon S3 加载数据。
- 's3://copy_from_s3_manifest_file'
-
为列出了要加载的数据文件的清单文件指定 Amazon S3 对象键。's3://copy_from_s3_manifest_file' 参数必须显式引用单个文件,例如
's3://amzn-s3-demo-bucket/manifest.txt'
。它不能引用键前缀。清单是 JSON 格式的文本文件,其中列出了要从 Amazon S3 加载的每个文件的 URL。URL 包含文件的桶名称和完整对象路径。在清单中指定的文件可以位于不同的桶中,但所有桶都必须位于 Amazon Redshift 集群所在的同一 Amazon 区域。如果某个文件被列出两次,那么该文件也会被加载两次。以下示例显示了加载三个文件的清单的 JSON。
{ "entries": [ {"url":"s3://amzn-s3-demo-bucket1/custdata.1","mandatory":true}, {"url":"s3://amzn-s3-demo-bucket1/custdata.2","mandatory":true}, {"url":"s3://amzn-s3-demo-bucket2/custdata.1","mandatory":false} ] }
需要双引号字符,并且必须是简单引号 (0x22),而不能是斜引号或“智能”引号。清单中的每个条目都可以选择性地包含
mandatory
标记。如果mandatory
设置为true
,则当 COPY 未找到该条目对应的文件时,该命令将会终止;否则,该命令将继续。mandatory
的默认值为false
。在从采用 ORC 或 Parquet 格式的数据文件中加载时,需要
meta
字段,如以下示例所示。{ "entries":[ { "url":"s3://amzn-s3-demo-bucket1/orc/2013-10-04-custdata", "mandatory":true, "meta":{ "content_length":99 } }, { "url":"s3://amzn-s3-demo-bucket2/orc/2013-10-05-custdata", "mandatory":true, "meta":{ "content_length":99 } } ] }
不能对清单文件进行加密或压缩,即使指定了 ENCRYPTED、GZIP、LZOP、BZIP2 或 ZSTD 选项。如果未找到指定的清单文件或清单文件的格式不正确,COPY 命令将返回错误。
如果使用了清单文件,则必须使用 COPY 命令指定 MANIFEST 参数。如果未指定 MANIFEST 参数,COPY 命令将假定使用 FROM 指定的文件是数据文件。
有关更多信息,请参阅 从 Amazon S3 加载数据。
- 授权
-
COPY 命令需要授权才能访问其他 Amazon 资源(包括 Amazon S3 、Amazon EMR、Amazon DynamoDB 和 Amazon EC2)中的数据。您可通过引用附加到您的集群的 Amazon Identity and Access Management (IAM) 角色(基于角色的访问控制)或者通过为用户提供访问凭证(基于密钥的访问控制)来提供授权。为了提高安全性和灵活性,我们建议使用基于 IAM 角色的访问控制。有关更多信息,请参阅 授权参数。
- MANIFEST
-
指定使用一个清单来标识要从 Amazon S3 加载的数据文件。如果使用了 MANIFEST 参数,则 COPY 将从 's3://copy_from_s3_manifest_file' 引用的清单中列出的文件加载数据。如果未找到清单文件或清单文件的格式不正确,COPY 将失败。有关更多信息,请参阅 使用清单指定数据文件。
- ENCRYPTED
-
一个子句,指定 Amazon S3 上输入文件的加密方法为:利用客户管理的密钥进行客户端加密。有关更多信息,请参阅 从 Amazon S3 中加载加密的数据文件。如果输入文件的加密方法为 Amazon S3 服务器端加密(SSE-KMS 或 SSE-S3),请不要指定 ENCRYPTED。COPY 会自动读取服务器端加密的文件。
如果您要指定 ENCRYPTED 参数,还必须指定 MASTER_SYMMETRIC_KEY 参数,或在
master_symmetric_key
字符串中包括 CREDENTIALS 值。如果加密文件采用了压缩格式,请添加 GZIP、LZOP、BZIP2 或 ZSTD 参数。
即使指定了 ENCRYPTED 选项,也不得加密清单文件和 JSONPaths 文件。
- MASTER_SYMMETRIC_KEY 'root_key'
-
用于在 Amazon S3 上加密数据文件的根对称密钥。如果指定了 MASTER_SYMMETRIC_KEY,还须指定 ENCRYPTED 参数。MASTER_SYMMETRIC_KEY 不能与 CREDENTIALS 参数配合使用。有关更多信息,请参阅 从 Amazon S3 中加载加密的数据文件。
如果加密文件采用了压缩格式,请添加 GZIP、LZOP、BZIP2 或 ZSTD 参数。
- REGION [AS] 'aws-region'
-
指定源数据所在的 Amazon 区域。当包含该数据的 Amazon 资源与 Amazon Redshift 集群不在同一区域时,从 Amazon S3 桶或 DynamoDB 表执行 COPY 的操作需要 REGION。
aws_region 的值必须与 Amazon Redshift 区域和端点表中所列的区域匹配。
如果指定了 REGION 参数,则所有资源(包括清单文件或多个 Amazon S3 桶)都必须位于指定区域内。
注意
对于包含数据的 Amazon S3 桶或 DynamoDB 表,跨区域传输数据将会产生额外费用。有关定价的更多信息,请参阅 Amazon S3 定价
页面上的将数据从 Amazon S3 移出到另一个 Amazon 区域和 Amazon DynamoDB 定价 页面上的移出数据。 预设情况下,COPY 假定数据位于 Amazon Redshift 集群所在的相同区域。
可选参数
对于从 Amazon S3 执行 COPY 的操作,还可以指定以下参数:
不支持的参数
对于从 Amazon S3 执行 COPY 的操作,不能使用以下参数:
-
SSH
-
READRATIO