从补丁 198 开始，Amazon Redshift 将不再支持创建新的 Python UDF。现有的 Python UDF 将继续正常运行至 2026 年 6 月 30 日。有关更多信息，请参阅[博客文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。
# COPY
| |
| --- |
| 从 2025 年 4 月 30 日起，COPY 和 UNLOAD 命令的客户端加密将不再向新客户开放。如果您在 2025 年 4 月 30 日之前的 12 个月内将客户端加密与 COPY 和 UNLOAD 命令结合使用，则在 2026 年 4 月 30 日之前，可以继续将客户端加密与 COPY 和 UNLOAD 命令结合使用。2026 年 4 月 30 日之后，您无法使用客户端加密进行 COPY 和 UNLOAD。我们建议您尽快切换到使用客户端加密进行 COPY 和 UNLOAD。如果您已经在使用客户端加密进行 COPY 和 UNLOAD，则没有任何变化，您可以在不更改查询的情况下继续使用它。有关 COPY 和 UNLOAD 的加密的更多信息，请参阅下面的 ENCRYPTED 参数。 |
将数据从数据文件或 Amazon DynamoDB 表加载到表中。这些文件可以位于 Amazon Simple Storage Service (Amazon S3) 桶、Amazon EMR 集群或可使用 Secure Shell (SSH) 连接访问的远程主机中。
**注意**
Amazon Redshift Spectrum 外部表为只读。您无法对外部表进行 COPY。
COPY 命令会将输入数据作为额外的行附加到表中。
来自任何源的单个输入行的最大大小为 4 MB。
**Topics**
+ [所需的权限](#r_COPY-permissions)
+ [COPY 语法](#r_COPY-syntax)
+ [必需参数](#r_COPY-syntax-required-parameters)
+ [可选参数](#r_COPY-syntax-overview-optional-parameters)
+ [COPY 命令的使用说明和其它资源](#r_COPY-using-the-copy-command)
+ [COPY 命令示例](#r_COPY-using-the-copy-command-examples)
+ [COPY JOB](r_COPY-JOB.md)
+ [使用 TEMPLATE 进行 COPY](r_COPY-WITH-TEMPLATE.md)
+ [COPY 参数参考](r_COPY-parameters.md)
+ [使用说明](r_COPY_usage_notes.md)
+ [COPY 示例](r_COPY_command_examples.md)
## 所需的权限
要使用 COPY 命令，您必须对 Amazon Redshift 表拥有 [INSERT](r_GRANT.md#grant-insert) 权限。
## COPY 语法
```
COPY table-name
[ column-list ]
FROM data_source
authorization
[ [ FORMAT ] [ AS ] data_format ]
[ parameter [ argument ] [, ... ] ]
```
只需 3 个参数即可执行 COPY 操作：表名称、数据来源和对数据的访问的授权。
Amazon Redshift 扩展了 COPY 命令的功能，使您可以从多个数据来源加载多种数据格式的数据、控制对加载数据的访问权限、管理数据转换和管理加载操作。
以下各节介绍所需的 COPY 命令参数，并按功能对可选参数进行分组。其中还会介绍每个参数并说明各个选项如何配合使用。您可以通过使用按字母顺序排列的参数列表直接转到相应的参数说明。
## 必需参数
COPY 命令需要三个元素：
+ [Table Name](#r_COPY-syntax-overview-table-name)
+ [Data Source](#r_COPY-syntax-overview-data-source)
+ [Authorization](#r_COPY-syntax-overview-credentials)
最简单的 COPY 命令使用以下格式。
```
COPY table-name
FROM data-source
authorization;
```
以下示例创建一个名为 CATDEMO 的表，然后从 Amazon S3 中名为 `category_pipe.txt` 的数据文件加载包含样本数据的表。
```
create table catdemo(catid smallint, catgroup varchar(10), catname varchar(10), catdesc varchar(50));
```
在以下示例中，COPY 命令的数据来源是一个数据文件，名为 `category_pipe.txt`，位于名为 `redshift-downloads` 的 Amazon S3 桶的 `tickit` 文件夹中。COPY 命令有权通过 AWS Identity and Access Management (IAM) 角色访问 Amazon S3 桶。如果您的集群具有有权访问附加的 Amazon S3 的现有 IAM 角色，您可以在以下 COPY 命令中替换您的角色的 Amazon 资源名称 (ARN) 并执行该角色。
```
copy catdemo
from 's3://redshift-downloads/tickit/category_pipe.txt'
iam_role 'arn:aws:iam:::role/'
region 'us-east-1';
```
有关如何使用 COPY 命令加载示例数据的完整说明，包括从其他 AWS 区域加载数据的说明，请参阅《Amazon Redshift 入门指南》中的[从 Amazon S3 中加载示例数据](https://docs.aws.amazon.com/redshift/latest/gsg/rs-gsg-create-sample-db.html)。
*table-name*
COPY 命令的目标表的名称。该表必须已存在于数据库中。该表可以是临时的或永久的。COPY 命令会将新输入数据追加到该表中的任何现有行。
FROM *data-source*
要加载到目标表中的源数据的位置。可使用某些数据来源指定清单文件。
最常用的数据存储库是 Amazon S3 桶。您还可以从位于 Amazon EMR 集群中、位于 Amazon EC2 实例中或位于您的集群可使用 SSH 连接访问的远程主机中的数据文件加载，或者也可以直接从 DynamoDB 表加载。
+ [从 Amazon S3 执行 COPY 操作](copy-parameters-data-source-s3.md)
+ [从 Amazon EMR 执行 COPY 操作](copy-parameters-data-source-emr.md)
+ [从远程主机中执行 COPY 操作 (SSH)](copy-parameters-data-source-ssh.md)
+ [从 Amazon DynamoDB 执行 COPY 操作](copy-parameters-data-source-dynamodb.md)
授权
一个子句，指示您的集群用于访问其他 AWS 资源的身份验证和授权的方法。COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3、Amazon EMR、Amazon DynamoDB 和 Amazon EC2）中的数据。您可通过引用附加到您的集群的 IAM 角色或通过为 IAM 用户提供访问密钥 ID 和秘密访问密钥来提供该授权。
+ [授权参数](copy-parameters-authorization.md)
+ [基于角色的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based)
+ [基于密钥的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-key-based)
## 可选参数
您可以选择性地指定 COPY 命令如何将字段数据映射到目标表中的列，定义源数据属性以便让 COPY 命令正确读取和分析源数据，以及管理 COPY 命令在加载过程中执行的操作。
+ [列映射选项](copy-parameters-column-mapping.md)
+ [数据格式参数](#r_COPY-syntax-overview-data-format)
+ [数据转换参数](#r_COPY-syntax-overview-data-conversion)
+ [数据加载操作](#r_COPY-syntax-overview-data-load)
### 列映射
默认情况下，COPY 会按字段在数据文件中出现的相同顺序将字段值插入到目标表的列中。如果默认列顺序不起作用，则可以指定一个列列表或使用 JSONPath 表达式将源数据字段映射到目标列。
+ [Column List](copy-parameters-column-mapping.md#copy-column-list)
+ [JSONPaths File](copy-parameters-column-mapping.md#copy-column-mapping-jsonpaths)
### 数据格式参数
您可以从固定宽度、字符分隔、逗号分隔值 (CSV)、JSON 格式的文本文件加载数据，也可从 Avro 文件加载数据。
默认情况下，COPY 命令要求源数据位于字符分隔的 UTF-8 文本文件中。默认分隔符是竖线字符 (\$1)。如果源数据采用的是其他格式，请使用以下参数指定数据格式。
+ [FORMAT](copy-parameters-data-format.md#copy-format)
+ [CSV](copy-parameters-data-format.md#copy-csv)
+ [DELIMITER](copy-parameters-data-format.md#copy-delimiter)
+ [FIXEDWIDTH](copy-parameters-data-format.md#copy-fixedwidth)
+ [SHAPEFILE](copy-parameters-data-format.md#copy-shapefile)
+ [AVRO](copy-parameters-data-format.md#copy-avro)
+ [JSON format for COPY](copy-parameters-data-format.md#copy-json)
+ [ENCRYPTED](copy-parameters-data-source-s3.md#copy-encrypted)
+ [BZIP2](copy-parameters-file-compression.md#copy-bzip2)
+ [GZIP](copy-parameters-file-compression.md#copy-gzip)
+ [LZOP](copy-parameters-file-compression.md#copy-lzop)
+ [PARQUET](copy-parameters-data-format.md#copy-parquet)
+ [ORC](copy-parameters-data-format.md#copy-orc)
+ [ZSTD](copy-parameters-file-compression.md#copy-zstd)
### 数据转换参数
在加载表时，COPY 会尝试将源数据中的字符串隐式转换为目标列的数据类型。如果您需要指定不同于默认行为的转换，或者默认转换会产生错误，则可以通过指定以下参数来管理数据转换。
+ [ACCEPTANYDATE](copy-parameters-data-conversion.md#copy-acceptanydate)
+ [ACCEPTINVCHARS](copy-parameters-data-conversion.md#copy-acceptinvchars)
+ [BLANKSASNULL](copy-parameters-data-conversion.md#copy-blanksasnull)
+ [DATEFORMAT](copy-parameters-data-conversion.md#copy-dateformat)
+ [EMPTYASNULL](copy-parameters-data-conversion.md#copy-emptyasnull)
+ [ENCODING](copy-parameters-data-conversion.md#copy-encoding)
+ [ESCAPE](copy-parameters-data-conversion.md#copy-escape)
+ [EXPLICIT_IDS](copy-parameters-data-conversion.md#copy-explicit-ids)
+ [FILLRECORD](copy-parameters-data-conversion.md#copy-fillrecord)
+ [IGNOREBLANKLINES](copy-parameters-data-conversion.md#copy-ignoreblanklines)
+ [IGNOREHEADER](copy-parameters-data-conversion.md#copy-ignoreheader)
+ [NULL AS](copy-parameters-data-conversion.md#copy-null-as)
+ [REMOVEQUOTES](copy-parameters-data-conversion.md#copy-removequotes)
+ [ROUNDEC](copy-parameters-data-conversion.md#copy-roundec)
+ [TIMEFORMAT](copy-parameters-data-conversion.md#copy-timeformat)
+ [TRIMBLANKS](copy-parameters-data-conversion.md#copy-trimblanks)
+ [TRUNCATECOLUMNS](copy-parameters-data-conversion.md#copy-truncatecolumns)
### 数据加载操作
通过指定以下参数来管理加载操作的默认行为，以进行故障排除或缩短加载时间。
+ [COMPROWS](copy-parameters-data-load.md#copy-comprows)
+ [COMPUPDATE](copy-parameters-data-load.md#copy-compupdate)
+ [IGNOREALLERRORS](copy-parameters-data-load.md#copy-ignoreallerrors)
+ [MAXERROR](copy-parameters-data-load.md#copy-maxerror)
+ [NOLOAD](copy-parameters-data-load.md#copy-noload)
+ [STATUPDATE](copy-parameters-data-load.md#copy-statupdate)
## COPY 命令的使用说明和其它资源
有关如何使用 COPY 命令的更多信息，请参阅以下主题：
+ [使用说明](r_COPY_usage_notes.md)
+ [教程：从 Amazon S3 加载数据](tutorial-loading-data.md)
+ [Amazon Redshift 加载数据的最佳实践](c_loading-data-best-practices.md)
+ [使用 COPY 命令加载表](t_Loading_tables_with_the_COPY_command.md)
+ [从 Amazon S3 加载数据](t_Loading-data-from-S3.md)
+ [从 Amazon EMR 中加载数据](loading-data-from-emr.md)
+ [从远程主机中加载数据](loading-data-from-remote-hosts.md)
+ [从 Amazon DynamoDB 表中加载数据](t_Loading-data-from-dynamodb.md)
+ [解决数据加载问题](t_Troubleshooting_load_errors.md)
## COPY 命令示例
有关展示如何使用不同来源、不同格式和不同的 COPY 选项执行 COPY 操作的更多示例，请参阅[COPY 示例](r_COPY_command_examples.md)。
# COPY JOB
有关使用此命令的信息，请参阅[创建 S3 事件集成以自动从 Amazon S3 存储桶复制文件](loading-data-copy-job.md)。
管理将数据加载到表中的 COPY 命令。COPY JOB 命令是 COPY 命令的扩展，可自动从 Amazon S3 桶加载数据。当您创建 COPY 作业时，Amazon Redshift 会检测何时在指定路径中创建新的 Amazon S3 文件，然后自动加载这些文件，无需您的干预。加载数据时使用的参数与原始 COPY 命令中使用的参数相同。Amazon Redshift 保持跟踪加载的文件（基于文件名），以确认它们只加载一次。
**注意**
有关 COPY 命令的信息，包括用法、参数和权限，请参阅 [COPY](r_COPY.md)。
## 所需的权限
要使用 COPY JOB 命令，除了使用 COPY 所需的所有权限外，您还必须拥有以下权限之一：
+ Superuser
+ 以下所有权限：
+ 与在要 COPY 到的数据库中执行 COPY JOBS 操作相关的 CREATE、ALTER 或 DROP 限定范围权限。
+ 对要 COPY 到的架构的 USAGE 权限，或者对要 COPY 到的数据库中架构的 USAGE 限定范围权限。
+ 对要 COPY 到的表的 INSERT 权限，或者对要 COPY 到的架构或数据库中的表的 INSERT 限定范围权限。
使用 COPY 命令指定的 IAM 角色必须具有访问待加载数据的权限。有关更多信息，请参阅 [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](copy-usage_notes-access-permissions.md#copy-usage_notes-iam-permissions)。
## 语法
创建复制作业。COPY 命令的参数与复制作业一起保存。
您不能在事务块的范围内运行 COPY JOB CREATE。
```
COPY copy-command JOB CREATE job-name
[AUTO ON | OFF]
```
更改复制作业的配置。
```
COPY JOB ALTER job-name
[AUTO ON | OFF]
```
运行复制作业。使用存储的 COPY 命令参数。
```
COPY JOB RUN job-name
```
列出所有复制作业。
```
COPY JOB LIST
```
显示复制作业的详细信息。
```
COPY JOB SHOW job-name
```
删除复制作业。
您不能在事务区的范围内运行 COPY JOB DROP。
```
COPY JOB DROP job-name
```
## 参数
*copy-command*
COPY 命令将数据从 Amazon S3 加载到 Amazon Redshift。该子句包含用于定义 Amazon S3 桶、目标表、IAM 角色的 COPY 参数，以及加载数据时使用的其他参数。支持用于 Amazon S3 数据加载的所有 COPY 命令参数，但以下参数除外：
+ COPY JOB 不会摄取 COPY 命令指向的文件夹中已有的文件。只有在 COPY JOB 创建时间戳之后创建的文件才会被摄取。
+ 不能使用 MAXERROR 或 IGNOREALLERRORS 选项指定 COPY 命令。
+ 不能指定清单文件。COPY JOB 需要指定的 Amazon S3 位置来监控新创建的文件。
+ 不能使用访问密钥和私有密钥等授权类型指定 COPY 命令。仅支持使用 `IAM_ROLE` 参数进行授权的 COPY 命令。有关更多信息，请参阅 [授权参数](copy-parameters-authorization.md)。
+ COPY JOB 不支持与集群关联的默认 IAM 角色。必须在 COPY 命令中指定 `IAM_ROLE`。
有关更多信息，请参阅 [从 Amazon S3 执行 COPY 操作](copy-parameters-data-source-s3.md)。
*job-name*
用于引用 COPY JOB 的作业的名称。*job-name* 不能包含连字符（‐）。
[AUTO ON \$1 OFF]
该子句指示 Amazon S3 数据是否自动加载到 Amazon Redshift 表中。
+ 选项为 `ON` 时，Amazon Redshift 会监控源 Amazon S3 路径中新创建的文件，如果找到新创建的文件，则使用作业定义中的 COPY 参数运行 COPY 命令。这是默认值。
+ 选项为 `OFF` 时，Amazon Redshift 不会自动运行 COPY JOB。
## 使用说明
COPY 命令的选项要等到运行时才会验证。例如，在 COPY JOB 启动时，无效的 `IAM_ROLE` 或 Amazon S3 数据来源会导致出现运行时错误。
如果暂停集群，则不运行 COPY JOB。
要查询已加载的 COPY 命令文件和加载错误，请参见 [STL\$1LOAD\$1COMMITS](r_STL_LOAD_COMMITS.md)、[STL\$1LOAD\$1ERRORS](r_STL_LOAD_ERRORS.md) 和 [STL\$1LOADERROR\$1DETAIL](r_STL_LOADERROR_DETAIL.md)。有关更多信息，请参阅 [验证是否正确加载了数据](verifying-that-data-loaded-correctly.md)。
零 ETL 数据库不支持 COPY JOBS，因为它们在只读模式下运行。
## 示例
以下示例显示创建 COPY JOB 以从 Amazon S3 桶加载数据。
```
COPY public.target_table
FROM 's3://amzn-s3-demo-bucket/staging-folder'
IAM_ROLE 'arn:aws:iam::123456789012:role/MyLoadRoleName'
JOB CREATE my_copy_job_name
AUTO ON;
```
# 使用 TEMPLATE 进行 COPY
您可以将 Redshift 模板与 COPY 命令结合使用，以简化命令语法并确保数据加载操作间的一致性。无需重复指定相同的格式化参数，而是在模板中定义它们一次，然后在 COPY 命令中引用模板。使用模板时，COPY 命令会将模板中的参数与在命令中直接指定的任何参数相结合。如果同一个参数同时出现在模板和命令中，则命令参数优先。有关更多信息，请参阅 [CREATE TEMPLATE](r_CREATE_TEMPLATE.md)。
可以使用以下各项创建 COPY 命令的模板：
+ [数据格式参数](copy-parameters-data-format.md)
+ [文件压缩参数](copy-parameters-file-compression.md)
+ [数据转换参数](copy-parameters-data-conversion.md)
+ [数据加载操作](copy-parameters-data-load.md)
有关支持的参数的完整列表，请参阅 [COPY](r_COPY.md) 命令。
## 所需的权限
要在 COPY 命令中使用模板，您必须拥有：
+ 执行 COPY 命令所需的所有权限（请参阅[所需的权限](r_COPY.md#r_COPY-permissions)）
+ 以下模板权限之一：
+ 超级用户权限
+ 对模板拥有 USAGE 权限，并对包含模板的架构拥有 USAGE 权限
## 语法
```
COPY target_table FROM 's3://...'
authorization
[ option, ...]
USING TEMPLATE [database_name.][schema_name.]template_name;
```
## 参数
*database\$1name*
（可选）模板所在数据库的名称。如果未指定，则使用当前数据库。
*schema\$1name*
（可选）模板所在架构的名称。如果未指定，则在当前搜索路径中搜索模板。
*template\$1name*
COPY 中要使用的模板的名称。
## 使用说明
+ 仍必须在 COPY 命令中指定特定于命令的参数（源、目标、授权）。
+ 模板不能包含 COPY 命令的清单文件规范。
## 示例
以下示例演示如何创建模板并在 COPY 命令中使用它：
```
CREATE TEMPLATE public.test_template FOR COPY AS
CSV DELIMITER '|' IGNOREHEADER 1 MAXERROR 100;
COPY public.target_table
FROM 's3://amzn-s3-demo-bucket/staging-folder'
IAM_ROLE 'arn:aws:iam::123456789012:role/MyLoadRoleName'
USING TEMPLATE public.test_template;
```
当某个参数同时存在于模板和命令中时，命令参数优先。在此示例中，如果模板 `public.test_template` 包含 `DELIMITER '|'`，但 COPY 命令指定 `DELIMITER ','`，则将使用命令中的逗号分隔符 (`,`)，而不是模板中的管道分隔符 (`|`)。
```
COPY public.target_table
FROM 's3://amzn-s3-demo-bucket/staging-folder'
IAM_ROLE 'arn:aws:iam::123456789012:role/MyLoadRoleName'
DELIMITER ','
USING TEMPLATE public.test_template;
```
# COPY 参数参考
COPY 有许多可以在多种情况下使用的参数。但是，并不是所有参数在每种情况下都受支持。例如，要从 ORC 或 PARQUET 文件加载，支持的参数数量有限。有关更多信息，请参阅 [从列式数据格式中执行 COPY 操作](copy-usage_notes-copy-from-columnar.md)。
**Topics**
+ [数据来源](copy-parameters-data-source.md)
+ [授权参数](copy-parameters-authorization.md)
+ [列映射选项](copy-parameters-column-mapping.md)
+ [数据格式参数](copy-parameters-data-format.md)
+ [文件压缩参数](copy-parameters-file-compression.md)
+ [数据转换参数](copy-parameters-data-conversion.md)
+ [数据加载操作](copy-parameters-data-load.md)
+ [按字母顺序排列的参数列表](r_COPY-alphabetical-parm-list.md)
# 数据来源
您可以从位于 Amazon S3 桶中、位于 Amazon EMR 集群中或位于您的集群可使用 SSH 连接访问的远程主机上的文本文件加载数据。您也可以直接从 DynamoDB 表加载数据。
来自任何源的单个输入行的最大大小为 4 MB。
要将表中的数据导出到 Amazon S3 中的一组文件，请使用 [UNLOAD](r_UNLOAD.md) 命令。
**Topics**
+ [从 Amazon S3 执行 COPY 操作](copy-parameters-data-source-s3.md)
+ [从 Amazon EMR 执行 COPY 操作](copy-parameters-data-source-emr.md)
+ [从远程主机中执行 COPY 操作 (SSH)](copy-parameters-data-source-ssh.md)
+ [从 Amazon DynamoDB 执行 COPY 操作](copy-parameters-data-source-dynamodb.md)
# 从 Amazon S3 执行 COPY 操作
要从位于一个或多个 S3 桶中的文件加载数据，请使用 FROM 子句指示 COPY 在 Amazon S3 中查找文件的方式。您可以提供数据文件的对象路径作为 FROM 子句的一部分，也可以提供包含了 Amazon S3 对象路径列表的清单文件的位置。从 Amazon S3 执行 COPY 操作将使用 HTTPS 连接。确保将 S3 IP 范围添加到您的允许列表中。要了解有关所需 S3 IP 范围的更多信息，请参阅[网络隔离](https://docs.aws.amazon.com//redshift/latest/mgmt/security-network-isolation.html#network-isolation)。
**重要**
如果包含数据文件的 Amazon S3 桶未驻留在您的集群所在的 AWS 区域内，则必须使用 [REGION](#copy-region) 参数指定数据所在的区域。
**Topics**
+ [语法](#copy-parameters-data-source-s3-syntax)
+ [示例](#copy-parameters-data-source-s3-examples)
+ [可选参数](#copy-parameters-data-source-s3-optional-parms)
+ [不支持的参数](#copy-parameters-data-source-s3-unsupported-parms)
## 语法
```
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 文件编码的更多信息，请参阅[数据转换参数](copy-parameters-data-conversion.md)。
's3://*copy\$1from\$1s3\$1objectpath*'
指定包含数据的 Amazon S3 对象的路径，例如 `'s3://amzn-s3-demo-bucket/custdata.txt'`。*s3://copy\$1from\$1s3\$1objectpath* 参数可引用单个文件或者具有相同键前缀的一组对象或文件夹。例如，名称 `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](#copy-manifest-file)。
如果包含数据文件的 S3 桶未驻留在您的集群所在的 AWS 区域内，则必须使用 [REGION](#copy-region) 参数指定数据所在的区域。
有关更多信息，请参阅 [从 Amazon S3 加载数据](t_Loading-data-from-S3.md)。
's3://*copy\$1from\$1s3\$1manifest\$1file*'
为列出了要加载的数据文件的清单文件指定 Amazon S3 对象键。*'s3://*copy\$1from\$1s3\$1manifest\$1file'** 参数必须显式引用单个文件，例如`'s3://amzn-s3-demo-bucket/manifest.txt'`。它不能引用键前缀。
清单是 JSON 格式的文本文件，其中列出了要从 Amazon S3 加载的每个文件的 URL。URL 包含文件的桶名称和完整对象路径。在清单中指定的文件可以位于不同的桶中，但所有桶都必须位于 Amazon Redshift 集群所在的同一 AWS 区域。如果某个文件被列出两次，那么该文件也会被加载两次。以下示例显示了加载三个文件的清单的 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 加载数据](t_Loading-data-from-S3.md)。
*授权*
COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3 、Amazon EMR、Amazon DynamoDB 和 Amazon EC2）中的数据。您可通过引用附加到您的集群的 AWS Identity and Access Management (IAM) 角色（基于角色的访问控制）或者通过为用户提供访问凭证（基于密钥的访问控制）来提供授权。为了提高安全性和灵活性，我们建议使用基于 IAM 角色的访问控制。有关更多信息，请参阅 [授权参数](copy-parameters-authorization.md)。
MANIFEST
指定使用一个清单来标识要从 Amazon S3 加载的数据文件。如果使用了 MANIFEST 参数，则 COPY 将从 *'s3://copy\$1from\$1s3\$1manifest\$1file'* 引用的清单中列出的文件加载数据。如果未找到清单文件或清单文件的格式不正确，COPY 将失败。有关更多信息，请参阅 [使用清单指定数据文件](loading-data-files-using-manifest.md)。
ENCRYPTED
一个子句，指定 Amazon S3 上输入文件的加密方法为：利用客户管理的密钥进行客户端加密。有关更多信息，请参阅 [从 Amazon S3 中加载加密的数据文件](c_loading-encrypted-files.md)。如果输入文件的加密方法为 Amazon S3 服务器端加密（SSE-KMS 或 SSE-S3），请不要指定 ENCRYPTED。COPY 会自动读取服务器端加密的文件。
如果您要指定 ENCRYPTED 参数，还必须指定 [MASTER_SYMMETRIC_KEY](#copy-master-symmetric-key) 参数，或在 **master\$1symmetric\$1key** 字符串中包括 [使用 CREDENTIALS 参数](copy-parameters-authorization.md#copy-credentials) 值。
如果加密文件采用了压缩格式，请添加 GZIP、LZOP、BZIP2 或 ZSTD 参数。
即使指定了 ENCRYPTED 选项，也不得加密清单文件和 JSONPaths 文件。
MASTER\$1SYMMETRIC\$1KEY '*root\$1key*'
用于在 Amazon S3 上加密数据文件的根对称密钥。如果指定了 MASTER\$1SYMMETRIC\$1KEY，还须指定 [ENCRYPTED](#copy-encrypted) 参数。MASTER\$1SYMMETRIC\$1KEY 不能与 CREDENTIALS 参数配合使用。有关更多信息，请参阅 [从 Amazon S3 中加载加密的数据文件](c_loading-encrypted-files.md)。
如果加密文件采用了压缩格式，请添加 GZIP、LZOP、BZIP2 或 ZSTD 参数。
REGION [AS] '*aws-region*'
指定源数据所在的 AWS 区域。当包含该数据的 AWS 资源与 Amazon Redshift 集群不在同一区域时，从 Amazon S3 桶或 DynamoDB 表执行 COPY 的操作需要 REGION。
*aws\$1region* 的值必须与 [Amazon Redshift 区域和端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#redshift_region)表中所列的区域匹配。
如果指定了 REGION 参数，则所有资源（包括清单文件或多个 Amazon S3 桶）都必须位于指定区域内。
对于包含数据的 Amazon S3 桶或 DynamoDB 表，跨区域传输数据将会产生额外费用。有关定价的更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)页面上的**将数据从 Amazon S3 移出到另一个 AWS 区域**和 [Amazon DynamoDB 定价](https://aws.amazon.com/dynamodb/pricing/)页面上的**移出数据**。
预设情况下，COPY 假定数据位于 Amazon Redshift 集群所在的相同区域。
## 可选参数
对于从 Amazon S3 执行 COPY 的操作，还可以指定以下参数：
+ [列映射选项](copy-parameters-column-mapping.md)
+ [数据格式参数](copy-parameters-data-format.md#copy-data-format-parameters)
+ [数据转换参数](copy-parameters-data-conversion.md)
+ [数据加载操作](copy-parameters-data-load.md)
## 不支持的参数
对于从 Amazon S3 执行 COPY 的操作，不能使用以下参数：
+ SSH
+ READRATIO
# 从 Amazon EMR 执行 COPY 操作
您可以使用 COPY 命令从一个具有如下配置的 Amazon EMR 集群并行加载数据：将文本文件以固定宽度文件、字符分隔文件、CSV 文件、JSON 格式文件或 Avro 文件的形式写入到集群的 Hadoop Distributed File System (HDFS)。
**Topics**
+ [语法](#copy-parameters-data-source-emr-syntax)
+ [示例](#copy-parameters-data-source-emr-example)
+ [参数](#copy-parameters-data-source-emr-parameters)
+ [支持的参数](#copy-parameters-data-source-emr-optional-parms)
+ [不支持的参数](#copy-parameters-data-source-emr-unsupported-parms)
## 语法
```
FROM 'emr://emr_cluster_id/hdfs_filepath'
authorization
[ optional_parameters ]
```
## 示例
以下示例从一个 Amazon EMR 集群加载数据。
```
copy sales
from 'emr://j-SAMPLE2B500FC/myoutput/part-*'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
## 参数
FROM
要加载的数据的源。
'emr://*emr\$1cluster\$1id*/*hdfs\$1file\$1path*'
Amazon EMR 集群的唯一标识符和引用 COPY 命令的数据文件的 HDFS 文件路径。HDFS 数据文件名不能包含通配符星号 (\$1) 和问号 (?)。
在 COPY 操作完成前，Amazon EMR 集群必须持续运行。如果在 COPY 操作完成前更改或删除了任何 HDFS 数据文件，则您可能得到意外的结果，或者 COPY 操作可能会失败。
您可以使用通配符星号 (\$1) 和问号 (?) 作为 *hdfs\$1file\$1path* 参数的一部分来指定要加载的多个文件。例如，`'emr://j-SAMPLE2B500FC/myoutput/part*'` 标识文件 `part-0000`、`part-0001`，等等。如果文件路径不包含通配符，则将其视为文字字符串。如果您仅指定一个文件夹名称，则 COPY 将尝试加载该文件夹中的所有文件。
如果您使用通配符或仅使用文件夹名称，请确认将不会加载不需要的文件。例如，某些流程可能会将日志文件写入到输出文件夹。
有关更多信息，请参阅 [从 Amazon EMR 中加载数据](loading-data-from-emr.md)。
*授权*
COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3 、Amazon EMR、Amazon DynamoDB 和 Amazon EC2）中的数据。您可通过引用附加到您的集群的 AWS Identity and Access Management (IAM) 角色（基于角色的访问控制）或者通过为用户提供访问凭证（基于密钥的访问控制）来提供授权。为了提高安全性和灵活性，我们建议使用基于 IAM 角色的访问控制。有关更多信息，请参阅 [授权参数](copy-parameters-authorization.md)。
## 支持的参数
对于从 Amazon EMR 执行 COPY 的操作，还可以指定以下参数：
+ [列映射选项](copy-parameters-column-mapping.md)
+ [数据格式参数](copy-parameters-data-format.md#copy-data-format-parameters)
+ [数据转换参数](copy-parameters-data-conversion.md)
+ [数据加载操作](copy-parameters-data-load.md)
## 不支持的参数
对于从 Amazon EMR 执行 COPY 的操作，不能使用以下参数：
+ ENCRYPTED
+ MANIFEST
+ REGION
+ READRATIO
+ SSH
# 从远程主机中执行 COPY 操作 (SSH)
您可使用 COPY 命令从一台或多台远程主机并行加载数据，例如 Amazon Elastic Compute Cloud (Amazon EC2) 实例或其他计算机。COPY 使用 Secure Shell (SSH) 连接到远程主机并在远程主机上运行命令以生成文本输出。远程主机可以是 EC2 Linux 实例或配置为接受 SSH 连接的另一台 Unix 或 Linux 计算机。Amazon Redshift 可连接到多台主机，并可以打开到每台主机的多个 SSH 连接。Amazon Redshift 会通过每个连接发送一个唯一命令来生成到主机标准输出的文本输出，然后 Amazon Redshift 会像读取文本文件一样读取它。
使用 FROM 子句指定一个清单文件的 Amazon S3 对象键，该清单文件提供 COPY 用于建立 SSH 连接并执行远程命令的信息。
**Topics**
+ [语法](#copy-parameters-data-source-ssh-syntax)
+ [示例](#copy-parameters-data-source-ssh-examples)
+ [参数](#copy-parameters-data-source-ssh-parameters)
+ [可选参数](#copy-parameters-data-source-ssh-optional-parms)
+ [不支持的参数](#copy-parameters-data-source-ssh-unsupported-parms)
**重要**
如果包含清单文件的 S3 桶未驻留在您的集群所在的 AWS 区域内，则必须使用 REGION 参数指定该桶所在的区域。
## 语法
```
FROM 's3://'ssh_manifest_file' }
authorization
SSH
| optional-parameters
```
## 示例
以下示例使用清单文件从使用 SSH 的远程主机加载数据。
```
copy sales
from 's3://amzn-s3-demo-bucket/ssh_manifest'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
ssh;
```
## 参数
FROM
要加载的数据的源。
's3://*copy\$1from\$1ssh\$1manifest\$1file*'
COPY 命令可连接到使用 SSH 的多台主机，并可以与每台主机建立多个 SSH 连接。COPY 通过每个主机连接运行一个命令，然后将来自这些命令的输出并行加载到表中。*s3://copy\$1from\$1ssh\$1manifest\$1file* 参数指定一个清单文件的 Amazon S3 对象键，该清单文件提供 COPY 将用于建立 SSH 连接并执行远程命令的信息。
*s3://copy\$1from\$1ssh\$1manifest\$1file* 参数必须显式引用单个文件；它不能是键前缀。下面是一个示例：
```
's3://amzn-s3-demo-bucket/ssh_manifest.txt'
```
清单文件是 Amazon Redshift 用于连接主机的文本文件，采用 JSON 格式。清单文件指定 SSH 主机端点以及将在主机上运行的用于将数据返回到 Amazon Redshift 的命令。另外，您还可以包含主机公有密钥、登录用户名和每个条目的 mandatory 标志。以下示例显示了用于创建两个 SSH 连接的清单文件：
```
{
"entries": [
{"endpoint":"",
"command": "",
"mandatory":true,
"publickey": "",
"username": ""},
{"endpoint":"",
"command": "",
"mandatory":true,
"publickey": "",
"username": ""}
]
}
```
该清单文件为每个 SSH 连接包含一个 `"entries"` 结构。您可以与单台主机建立多个连接或与多台主机建立多个连接。如上所示，字段名称和值均需要使用双引号字符。引号字符必须是简单引号 (0x22)，而不能是倾斜引号或“智能”引号。唯一一个不需要双引号字符的值是 `"mandatory"` 字段的布尔值 `true` 或 `false`。
以下列表介绍了清单文件中的字段。
endpoint
主机的 URL 地址或 IP 地址，例如 `"ec2-111-222-333.compute-1.amazonaws.com"` 或 `"198.51.100.0"`。
命令
命令通过主机运行，用以产生 gzip、lzop、bzip2 或 zstd 格式的文本输出或二进制输出。该命令可以是用户 *"host\$1user\$1name"* 有权运行的任何命令。该命令可以是像打印文件这样简单的命令，也可以查询数据库或启动脚本。输出（文本文件、gzip 二进制文件、lzop 二进制文件或 bzip2 二进制文件）必须采用 Amazon Redshift COPY 命令可摄取的形式。有关更多信息，请参阅 [准备输入数据](t_preparing-input-data.md)。
publickey
（可选）主机的公有密钥。如果提供了公有密钥，Amazon Redshift 将使用它来标识主机。如果未提供公有密钥，Amazon Redshift 将不会尝试主机标识。例如，如果远程主机的公有密钥是 `ssh-rsa AbcCbaxxx…Example root@amazon.com`，请在公有密钥字段中键入以下文本：`"AbcCbaxxx…Example"`
mandatory
（可选）一个子句，指示在连接尝试失败时 COPY 命令是否应失败。默认为 `false`。如果 Amazon Redshift 未成功建立至少一个连接，COPY 命令将失败。
username
（可选）将用于登录到主机系统并执行远程命令的用户名。用户登录名必须与用于将 Amazon Redshift 集群的公有密钥添加到主机的授权密钥文件的登录名相同。默认用户名为 `redshift`。
有关创建清单文件的更多信息，请参阅[加载数据的过程](loading-data-from-remote-hosts.md#load-from-host-process)。
要从远程主机执行 COPY 操作，则必须在 COPY 命令中指定 SSH 参数。如果未指定 SSH 参数，COPY 命令将假定使用 FROM 指定的文件是数据文件，操作将会失败。
如果使用自动压缩，COPY 命令将执行两个数据读取操作，这意味着它将执行远程命令两次。第一个读取操作用于提供压缩分析的数据样本，第二个读取操作实际加载数据。如果执行远程命令两次可能会导致问题，则应禁用自动压缩。要禁用自动压缩，请在运行 COPY 命令时将 COMPUPDATE 参数设置为 OFF。有关更多信息，请参阅 [使用自动压缩加载表](c_Loading_tables_auto_compress.md)。
有关从 SSH 执行 COPY 操作的详细过程，请参阅[从远程主机中加载数据](loading-data-from-remote-hosts.md)。
*授权*
COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3 、Amazon EMR、Amazon DynamoDB 和 Amazon EC2）中的数据。您可通过引用附加到您的集群的 AWS Identity and Access Management (IAM) 角色（基于角色的访问控制）或者通过为用户提供访问凭证（基于密钥的访问控制）来提供授权。为了提高安全性和灵活性，我们建议使用基于 IAM 角色的访问控制。有关更多信息，请参阅 [授权参数](copy-parameters-authorization.md)。
SSH
一个子句，指定要从使用 SSH 协议的远程主机加载数据。如果指定 SSH，则必须使用 [s3://copy_from_ssh_manifest_file](#copy-ssh-manifest) 参数提供清单文件。
如果您通过 SSH 在远程 VPC 中使用私有 IP 地址从主机进行复制，则 VPC 必须启用增强型 VPC 路由。有关增强型 VPC 路由的更多信息，请参阅 [Amazon Redshift 增强型 VPC 路由](https://docs.aws.amazon.com/redshift/latest/mgmt/enhanced-vpc-routing.html)。
## 可选参数
对于从 SSH 执行 COPY 的操作，还可以选择指定以下参数：
+ [列映射选项](copy-parameters-column-mapping.md)
+ [数据格式参数](copy-parameters-data-format.md#copy-data-format-parameters)
+ [数据转换参数](copy-parameters-data-conversion.md)
+ [数据加载操作](copy-parameters-data-load.md)
## 不支持的参数
对于从 SSH 执行 COPY 的操作，不能使用以下参数：
+ ENCRYPTED
+ MANIFEST
+ READRATIO
# 从 Amazon DynamoDB 执行 COPY 操作
要从现有 DynamoDB 表加载数据，请使用 FROM 子句指定 DynamoDB 表名称。
**Topics**
+ [语法](#copy-parameters-data-source-dynamodb-syntax)
+ [示例](#copy-parameters-data-source-dynamodb-examples)
+ [可选参数](#copy-parameters-data-source-dynamodb-optional-parms)
+ [不支持的参数](#copy-parameters-data-source-dynamodb-unsupported-parms)
**重要**
如果 DynamoDB 表未驻留在您的 Amazon Redshift 集群所在的区域内，则必须使用 REGION 参数指定该数据所在的区域。
## 语法
```
FROM 'dynamodb://table-name'
authorization
READRATIO ratio
| REGION [AS] 'aws_region'
| optional-parameters
```
## 示例
以下示例从 DynamoDB 表加载数据。
```
copy favoritemovies from 'dynamodb://ProductCatalog'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
readratio 50;
```
### 参数
FROM
要加载的数据的源。
'dynamodb://*table-name*'
包含数据的 DynamoDB 表的名称，例如 `'dynamodb://ProductCatalog'`。有关 DynamoDB 属性如何映射到 Amazon Redshift 列的详细信息，请参阅[从 Amazon DynamoDB 表中加载数据](t_Loading-data-from-dynamodb.md)。
DynamoDB 表名称对于由 AWS 访问凭证标识的 AWS 账户是唯一的。
*授权*
COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3 、Amazon EMR、DynamoDB 和 Amazon EC2）中的数据。您可通过引用附加到您的集群的 AWS Identity and Access Management (IAM) 角色（基于角色的访问控制）或者通过为用户提供访问凭证（基于密钥的访问控制）来提供授权。为了提高安全性和灵活性，我们建议使用基于 IAM 角色的访问控制。有关更多信息，请参阅 [授权参数](copy-parameters-authorization.md)。
READRATIO [AS] *ratio*
DynamoDB 表的预配置吞吐量中要用于数据加载的部分所占的百分比。从 DynamoDB 执行 COPY 的操作需要 READRATIO。它不能在从 Amazon S3 执行 COPY 的操作中使用。我们强烈建议您将此比率设置为一个低于平均的未使用预配置吞吐量的值。有效值为整数 1–200。
将 READRATIO 设置为 100 或更大值将使 Amazon Redshift 消耗 DynamoDB 表的全部预配置吞吐量，从而严重降低 COPY 会话期间对同一个表进行的并行读取操作的性能。写入流量不受影响。允许使用大于 100 的值来应对 Amazon Redshift 无法满足表的预配置吞吐量的罕见情况。如果将 DynamoDB 中的数据持续加载到 Amazon Redshift，请考虑按时间序列组织 DynamoDB 表以将实时流量与 COPY 操作分离。
## 可选参数
对于从 Amazon DynamoDB 执行 COPY 的操作，还可以指定以下参数：
+ [列映射选项](copy-parameters-column-mapping.md)
+ 支持以下数据转换参数：
+ [ACCEPTANYDATE](copy-parameters-data-conversion.md#copy-acceptanydate)
+ [BLANKSASNULL](copy-parameters-data-conversion.md#copy-blanksasnull)
+ [DATEFORMAT](copy-parameters-data-conversion.md#copy-dateformat)
+ [EMPTYASNULL](copy-parameters-data-conversion.md#copy-emptyasnull)
+ [ROUNDEC](copy-parameters-data-conversion.md#copy-roundec)
+ [TIMEFORMAT](copy-parameters-data-conversion.md#copy-timeformat)
+ [TRIMBLANKS](copy-parameters-data-conversion.md#copy-trimblanks)
+ [TRUNCATECOLUMNS](copy-parameters-data-conversion.md#copy-truncatecolumns)
+ [数据加载操作](copy-parameters-data-load.md)
## 不支持的参数
对于从 DynamoDB 执行 COPY 的操作，不能使用以下参数：
+ 所有数据格式参数
+ ESCAPE
+ FILLRECORD
+ IGNOREBLANKLINES
+ IGNOREHEADER
+ NULL
+ REMOVEQUOTES
+ ACCEPTINVCHARS
+ MANIFEST
+ ENCRYPTED
# 授权参数
COPY 命令需要授权才能访问其他 AWS 资源（包括 Amazon S3、Amazon EMR、Amazon DynamoDB 和 Amazon EC2）中的数据。您通过引用附加到集群的 [AWS Identity and Access Management (IAM) 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)来提供授权（*基于角色的访问控制*）。您可以在 Amazon S3 上加密您的加载数据。
以下主题将提供有关身份验证选项的更多详细信息和示例：
+ [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](copy-usage_notes-access-permissions.md#copy-usage_notes-iam-permissions)
+ [基于角色的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based)
+ [基于密钥的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-key-based)
使用以下参数之一为 COPY 命令提供授权：
+ [使用 IAM\$1ROLE 参数](#copy-iam-role) parameter
+ [使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 参数](#copy-access-key-id) 参数
+ [使用 CREDENTIALS 参数](#copy-credentials) 子句
## 使用 IAM\$1ROLE 参数
### IAM\$1ROLE
使用默认关键字让 Amazon Redshift 使用设置为默认值并在 COPY 命令运行时与集群关联的 IAM 角色。
使用 IAM 角色的 Amazon 资源名称 (ARN)，您的集群使用该角色进行身份验证和授权。如果您指定 IAM\$1ROLE，则无法使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY、SESSION\$1TOKEN 或 CREDENTIALS。
以下显示 IAM\$1ROLE 参数的语法。
```
IAM_ROLE { default | 'arn:aws:iam:::role/' }
```
有关更多信息，请参阅 [基于角色的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based)。
## 使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 参数
### ACCESS\$1KEY\$1ID、SECRET\$1ACCESS\$1KEY
不建议您使用此授权方法。
**注意**
我们强烈建议通过指定 IAM\$1ROLE 参数使用基于角色的身份验证，而不是提供纯文本形式的访问凭证。有关更多信息，请参阅 [基于角色的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based)。
### SESSION\$1TOKEN
与临时访问凭证配合使用的会话令牌。如果指定 SESSION\$1TOKEN，还必须使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 提供临时访问密钥凭证。如果指定 SESSION\$1TOKEN，则不能使用 IAM\$1ROLE 或 CREDENTIALS。有关更多信息，请参阅《IAM 用户指南》中的[临时安全凭证](copy-usage_notes-access-permissions.md#r_copy-temporary-security-credentials)。
**注意**
我们强烈建议使用基于角色的身份验证，而不是创建临时安全凭证。如果您授权使用 IAM 角色，Amazon Redshift 会自动为每个会话创建临时用户凭证。有关更多信息，请参阅 [基于角色的访问控制](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based)。
以下显示 SESSION\$1TOKEN 参数与 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 参数配合使用时的语法。
```
ACCESS_KEY_ID ''
SECRET_ACCESS_KEY ''
SESSION_TOKEN '';
```
如果指定 SESSION\$1TOKEN，则不能使用 CREDENTIALS 或 IAM\$1ROLE。
## 使用 CREDENTIALS 参数
### CREDENTIALS
一个子句，指示您的集群在访问包含数据文件或清单文件的其他 AWS 资源时将使用的方法。CREDENTIALS 参数不能与 IAM\$1ROLE 或 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 配合使用。
下面显示 CREDENTIALS 参数的语法。
```
[WITH] CREDENTIALS [AS] 'credentials-args'
```
**注意**
要获得更高的灵活性，我们建议使用 [IAM\$1ROLE](#copy-iam-role-iam) 参数，而不是 CREDENTIALS 参数。
（可选）如果使用了 [ENCRYPTED](copy-parameters-data-source-s3.md#copy-encrypted) 参数，*credentials-args* 字符串还将提供加密密钥。
*credentials-args* 字符串区分大小写且不得包含空格。
关键字 WITH 和 AS 是可选的，将被忽略。
您可指定 [role-based access control](copy-usage_notes-access-permissions.md#copy-usage_notes-access-role-based.phrase) 或 [key-based access control](copy-usage_notes-access-permissions.md#copy-usage_notes-access-key-based.phrase)。在任一情况下，IAM 角色或用户都必须具有访问指定 AWS 资源所需的权限。有关更多信息，请参阅 [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](copy-usage_notes-access-permissions.md#copy-usage_notes-iam-permissions)。
**注意**
为了保护您的 AWS 凭证和敏感数据，我们强烈建议使用基于角色的访问控制。
要指定基于角色的访问控制，请按以下格式提供 *credentials-args* 字符串。
```
'aws_iam_role=arn:aws:iam:::role/'
```
要使用临时令牌凭证，您必须提供临时访问密钥 ID、临时秘密访问密钥和临时令牌。*credentials-args* 字符串采用以下格式。
```
CREDENTIALS
'aws_access_key_id=;aws_secret_access_key=;token='
```
使用基于角色的访问控制及临时凭证的 COPY 命令类似于以下示例语句：
```
COPY customer FROM 's3://amzn-s3-demo-bucket/mydata'
CREDENTIALS
'aws_access_key_id=;aws_secret_access_key=;token='
```
有关更多信息，请参阅 [临时安全凭证](copy-usage_notes-access-permissions.md#r_copy-temporary-security-credentials)。
如果使用了 [ENCRYPTED](copy-parameters-data-source-s3.md#copy-encrypted) 参数，*credentials-args* 字符串将采用以下格式，其中 ** 是用于对文件进行加密的根密钥的值。
```
CREDENTIALS
';master_symmetric_key='
```
使用基于角色的访问控制及加密密钥的 COPY 命令类似于以下示例语句：
```
COPY customer FROM 's3://amzn-s3-demo-bucket/mydata'
CREDENTIALS
'aws_iam_role=arn:aws:iam:::role/;master_symmetric_key='
```
# 列映射选项
默认情况下，COPY 会按字段在数据文件中出现的相同顺序将值插入到目标表的列中。如果默认列顺序不起作用，则可以指定一个列列表或使用 JSONPath 表达式将源数据字段映射到目标列。
+ [Column List](#copy-column-list)
+ [JSONPaths File](#copy-column-mapping-jsonpaths)
## 列列表
您可以指定列名称的逗号分隔列表以将源数据字段加载到特定目标列中。这些列在 COPY 语句中可以采用任何顺序，但是，当从平面文件加载时（如在 Amazon S3 桶中），它们的顺序必须与源数据的顺序一致。
从 Amazon DynamoDB 表加载时，顺序并不重要。COPY 命令将从 DynamoDB 表中检索到的项中的属性名称与 Amazon Redshift 表中的列名进行匹配。有关更多信息，请参阅[从 Amazon DynamoDB 表中加载数据](t_Loading-data-from-dynamodb.md)
列列表的格式如下所示。
```
COPY tablename (column1 [,column2, ...])
```
如果列列表省略了目标表中的列，则 COPY 将加载目标列的 [DEFAULT](r_CREATE_TABLE_NEW.md#create-table-default) 表达式。
如果目标列没有默认值，则 COPY 将尝试加载 NULL。
如果 COPY 尝试将 NULL 分配到一个定义为 NOT NULL 的列，COPY 命令将失败。
如果 [IDENTITY](r_CREATE_TABLE_NEW.md#identity-clause) 列包含在列列表中，则还必须指定 [EXPLICIT_IDS](copy-parameters-data-conversion.md#copy-explicit-ids)；如果省略了 IDENTITY 列，则无法指定 EXPLICIT\$1IDS。如果未指定任何列列表，则该命令将如同指定了一个完整、有序的列列表一样来执行，如果也未指定 EXPLICIT\$1IDS，则会省略 IDENTITY 列。
如果某个列使用 GENERATED BY DEFAULT AS IDENTITY 进行定义，则可以复制该列。使用您提供的值生成或更新值。EXPLICIT\$1IDS 选项不是必需项。COPY 不会更新身份高级别水印。有关更多信息，请参阅 [GENERATED BY DEFAULT AS IDENTITY](r_CREATE_TABLE_NEW.md#identity-generated-bydefault-clause)。
## JSONPaths 文件
当从 JSON 或 Avro 格式的数据文件加载时，COPY 会将 JSON 或 Avro 源数据中的数据元素自动映射到目标表中的列。它的执行方式是通过将 Avro schema 中的字段名称与目标表或列列表中的列名称相匹配。
在某些情况下，您的列名称与字段名称不匹配，或者您需要映射到数据层次结构中的更深层次。在这些情况下，您可以使用 JSONPaths 文件将 JSON 或 Avro 数据元素显式映射到列。
有关更多信息，请参阅 [JSONPaths 文件](copy-parameters-data-format.md#copy-json-jsonpaths)。
# 数据格式参数
默认情况下，COPY 命令要求源数据是字符分隔的 UTF-8 文本。默认分隔符是竖线字符 (\$1)。如果源数据采用的是其他格式，请使用以下参数指定数据格式：
+ [FORMAT](#copy-format)
+ [CSV](#copy-csv)
+ [DELIMITER](#copy-delimiter)
+ [FIXEDWIDTH](#copy-fixedwidth)
+ [SHAPEFILE](#copy-shapefile)
+ [AVRO](#copy-avro)
+ [JSON format for COPY](#copy-json)
+ [PARQUET](#copy-parquet)
+ [ORC](#copy-orc)
除标准数据格式以外，COPY 支持 Amazon S3 中有关 COPY 的以下列式数据格式：
+ [ORC](#copy-orc)
+ [PARQUET](#copy-parquet)
支持列式中的 COPY，其中带有特定限制。有关更多信息，请参阅 [从列式数据格式中执行 COPY 操作](copy-usage_notes-copy-from-columnar.md)。数据格式参数
FORMAT [AS]
（可选）标识数据格式关键字。FORMAT 参数如下所述。
CSV [ QUOTE [AS] *'quote\$1character'* ]
支持在输入数据中使用 CSV 格式。要自动对分隔符、换行符和回车符进行转义，可用 QUOTE 参数指定的字符将字段括起来。默认引号字符是双引号 ( " )。当在字段中使用了引号字符时，应使用另一个引号字符对其进行转义。例如，如果引号字符为双引号，那么要插入字符串 `A "quoted" word`，输入文件应包含字符串 `"A ""quoted"" word"`。当使用了 CSV 参数时，默认分隔符为逗号 (,)。您可使用 DELIMITER 参数指定一个不同的分隔符。
当某个字段用引号括起来时，分隔符和引号字符之间的空格将被忽略。如果分隔符为空格字符（如制表符），则分隔符不会被视为空格。
CSV 不能与 FIXEDWIDTH、REMOVEQUOTES 或 ESCAPE 一起使用。
QUOTE [AS] *'quote\$1character'*
可选。指定在使用 CSV 参数时要用作引号字符的字符。默认值为双引号 (")。如果您使用 QUOTE 参数定义双引号以外的引号字符，则不需要对字段中的双引号进行转义。QUOTE 参数只能与 CSV 参数一起使用。AS 关键字是可选的。
DELIMITER [AS] ['*delimiter\$1char*']
指定用于在输入文件中分隔各个字段的字符，如竖线字符 (`|`)、逗号 (`,`)、制表符 (`\t`) 或多个字符，如 `|~|`。支持不可打印的字符。字符也可以用八进制表示为其 UTF-8 代码单元。对于八进制，使用格式“\$1ddd”，其中“d”是八进制数字（0–7）。默认分隔符是竖线字符 (`|`)，除非使用了 CSV 参数，在这种情况下，默认分隔符是逗号 (`,`)。AS 关键字是可选的。DELIMITER 不能与 FIXEDWIDTH 一起使用。
FIXEDWIDTH '*fixedwidth\$1spec*'
从一个文件中加载数据，该文件中的每个列是宽度固定的列，而不是由分隔符分隔的列。*fixedwidth\$1spec* 是用于指定用户定义的列标签和列宽度的字符串。列标签可以是文本字符串或整数，具体取决于用户的选择。列标签与列名称没有关联。标签/宽度对的顺序必须与表列的顺序完全一致。FIXEDWIDTH 不能与 CSV 或 DELIMITER 一起使用。在 Amazon Redshift 中，CHAR 和 VARCHAR 列的长度以字节表示，因此在准备要加载的文件时，请确保您指定的列宽度可容纳多字节字符的二进制长度。有关更多信息，请参阅 [字符类型](r_Character_types.md)。
*fixedwidth\$1spec* 的格式如下所示：
```
'colLabel1:colWidth1,colLabel:colWidth2, ...'
```
SHAPEFILE [ SIMPLIFY [AUTO] [*'tolerance'*] ]
支持在输入数据中使用 SHAPEFILE 格式。预设情况下，shapefile 的第一列是 `GEOMETRY` 或 `IDENTITY` 列。所有后续列都遵循 shapefile 中指定的顺序。
您不能将 SHAPEFILE 与 FIXEDWIDTH、REMOVEQUOTES 或 ESCAPE 一起使用。
要将 `GEOGRAPHY` 对象与 `COPY FROM SHAPEFILE` 一起使用，请首先提取到 `GEOMETRY` 列，然后将对象强制转换为 `GEOGRAPHY` 对象。
SIMPLIFY [*tolerance*]
（可选）使用 Ramer-Douglas-Peucker 算法和给定的容差简化摄入过程中的所有几何体。
SIMPLIFY AUTO [*tolerance*]
（可选）仅简化大于最大几何大小的几何体。这种简化使用 Ramer-Douglas-Peucker 算法和自动计算的容差（如果不超过指定容差）。此算法计算在指定容差范围内存储对象的大小。*公差*值是可选的。
有关加载 shapefile 的示例，请参阅[将 shapefile 加载到 Amazon Redshift](r_COPY_command_examples.md#copy-example-spatial-copy-shapefile)。
AVRO [AS] '*avro\$1option*'
指定源数据采用 Avro 格式。
从以下服务和协议执行 COPY 的操作支持 Avro 格式：
+ Amazon S3
+ Amazon EMR
+ 远程主机 (SSH)
从 DynamoDB 执行 COPY 的操作不支持 Avro。
Avro 是一个数据序列化协议。Avro 源文件包含一个定义数据结构的 schema。Avro schema 类型必须为 `record`。COPY 接受使用默认的非压缩编解码器及 `deflate` 和 `snappy` 压缩编解码器创建的 Avro 文件。有关 Avro 的更多信息，请转到 [Apache Avro](https://avro.apache.org/)。
*avro\$1option* 的有效值如下：
+ `'auto'`
+ `'auto ignorecase'`
+ `'s3://jsonpaths_file'`
默认为 `'auto'`。
COPY 会将 Avro 源数据中的数据元素自动映射到目标表中的列。它的执行方式是通过将 Avro schema 中的字段名称与目标表中的列名称相匹配。`'auto'` 的匹配区分大小写，`'auto ignorecase'` 的匹配不区分大小写。
Amazon Redshift 表中的列名称始终小写，因此，当您使用 `'auto'` 选项时，匹配的字段名称也必须为小写。如果字段名称不是全部小写，则可以使用 `'auto ignorecase'` 选项。使用默认的 `'auto'` 参数时，COPY 仅识别结构中的第一层字段，或*外部字段*。
要将列名称显式映射到 Avro 字段名称，您可以使用 [JSONPaths 文件](#copy-json-jsonpaths)。
默认情况下，COPY 会尝试将目标表中的所有列与 Avro 字段名称匹配。要加载列的子集，您可以选择性地指定包含列的列表。如果列列表中省略了目标表中的列，则 COPY 将加载目标列的 [DEFAULT](r_CREATE_TABLE_NEW.md#create-table-default) 表达式。如果目标列没有默认值，则 COPY 将尝试加载 NULL。如果某个列包含在列列表中，并且 COPY 在 Avro 数据中找不到匹配的字段，则 COPY 会尝试将 NULL 加载到该列中。
如果 COPY 尝试将 NULL 分配到一个定义为 NOT NULL 的列，COPY 命令将失败。
**Avro Schema**
Avro 源数据文件包含一个定义数据结构的 Schema。COPY 将读取作为 Avro 源数据文件的一部分的 schema 以将数据元素映射到目标表列。以下示例显示了一个 Avro schema。
```
{
"name": "person",
"type": "record",
"fields": [
{"name": "id", "type": "int"},
{"name": "guid", "type": "string"},
{"name": "name", "type": "string"},
{"name": "address", "type": "string"}]
}
```
Avro schema 是使用 JSON 格式定义的。顶级 JSON 对象包含三个名称-值对，这三个名称（即*键*）分别为 `"name"`、`"type"` 和 `"fields"`。
`"fields"` 键与定义数据结构中每个字段的名称和数据类型的对象数组配对。默认情况下，COPY 会自动将字段名称与列名称匹配。列名称始终为小写形式，因此匹配的字段名称也必须为小写形式，除非您指定了 `‘auto ignorecase’` 选项。与列名称不匹配的任何字段名称都将被忽略。顺序无关紧要。在上述示例中，COPY 将映射到列名称 `id`、`guid`、`name` 和 `address`。
由于存在默认的 `'auto'` 参数，COPY 只会将第一层对象映射到列。若要映射到 schema 中的更深层次，或者如果字段名称与列名称不匹配，请使用 JSONPaths 文件定义映射。有关更多信息，请参阅 [JSONPaths 文件](#copy-json-jsonpaths)。
如果与键关联的值是一个复杂的 Avro 数据类型（如字节、数组、记录、映射或链接），COPY 会将该值作为一个字符串加载。这里的字符串是数据的 JSON 表示形式。COPY 会将 Avro 枚举数据类型作为字符串加载，其中的内容是类型的名称。有关示例，请参阅 [从 JSON 格式数据执行的 COPY 操作](copy-usage_notes-copy-from-json.md)。
Avro 文件标头（包括 schema 和文件元数据）的最大大小为 1 MB。
单个 Avro 数据块的最大大小为 4 MB。这与最大行大小不同。如果超过了单个 Avro 数据块的最大大小，则即使生成的行大小未达到 4 MB 的行大小限制，COPY 命令也会失败。
在计算行大小时，Amazon Redshift 在内部对竖线字符 ( \$1 ) 计为两个字符。如果您的输入数据中包含大量竖线字符，则即使数据块小于 4 MB，行大小也可能超过 4 MB。
JSON [AS] '*json\$1option*'
源数据采用 JSON 格式。
从以下服务和协议执行 COPY 的操作支持 JSON 格式：
+ Amazon S3
+ 从 Amazon EMR 执行 COPY 操作
+ 从 SSH 执行 COPY 的操作
从 DynamoDB 执行 COPY 的操作不支持 JSON。
*json\$1option* 的有效值如下：
+ `'auto'`
+ `'auto ignorecase'`
+ `'s3://jsonpaths_file'`
+ `'noshred'`
默认为 `'auto'`。在加载 JSON 文档时，Amazon Redshift 不会将 JSON 结构的属性分解为多个列。
默认情况下，COPY 会尝试将目标表中的所有列与 JSON 字段名称键匹配。要加载列的子集，您可以选择性地指定包含列的列表。如果 JSON 字段名称键包含大写字符，则您可以使用 `'auto ignorecase'` 选项或 [JSONPaths 文件](#copy-json-jsonpaths) 将列名称显式地映射到 JSON 字段名称键。
如果列列表省略了目标表中的列，则 COPY 将加载目标列的 [DEFAULT](r_CREATE_TABLE_NEW.md#create-table-default) 表达式。如果目标列没有默认值，则 COPY 将尝试加载 NULL。如果某个列包含在列列表中，并且 COPY 在 JSON 数据中找不到匹配的字段，则 COPY 会尝试将 NULL 加载到该列。
如果 COPY 尝试将 NULL 分配到一个定义为 NOT NULL 的列，COPY 命令将失败。
COPY 会将 JSON 源数据中的数据元素映射到目标表中的列。它的操作方式是通过将源名称-值对中的*对象键*（即名称）与目标表中的列名称匹配。
请参阅以下有关每个 *json\$1option* 值的详细信息：
'auto'
使用此选项时，匹配区分大小写。Amazon Redshift 表中的列名称始终小写，因此，当您使用 `'auto'` 选项时，匹配的 JSON 字段名称也必须为小写。
“auto ignorecase”
使用此选项时，匹配不区分大小写。Amazon Redshift 表中的列名称始终为小写，因此，当您使用 `'auto ignorecase'` 选项时，相应的 JSON 字段名称可以是小写、大写或大小写混合。
's3://*jsonpaths\$1file*'
通过此选项，COPY 使用命名的 JSONPaths 文件将 JSON 源数据中的数据元素映射到目标表中的列。*`s3://jsonpaths_file`* 参数必须是显式引用单个文件的 Amazon S3 对象键。示例是 `'s3://amzn-s3-demo-bucket/jsonpaths.txt`'。参数不能为键前缀。有关使用 JSONPaths 文件的更多信息，请参阅 [JSONPaths 文件](#copy-json-jsonpaths)。
在某些情况下，由 `jsonpaths_file` 指定的文件的前缀与由 `copy_from_s3_objectpath` 为数据文件指定的路径的前缀相同。如果是这样，COPY 会将 JSONPaths 文件作为数据文件读取并返回错误。例如，假设您的数据文件使用对象路径 `s3://amzn-s3-demo-bucket/my_data.json`，并且您的 JSONPaths 文件是 `s3://amzn-s3-demo-bucket/my_data.jsonpaths`。在这种情况下，COPY 会尝试加载 `my_data.jsonpaths` 作为数据文件。
“noshred”
使用此选项，Amazon Redshift 不会在加载 JSON 文档时将 JSON 结构的属性分解为多个列。
## JSON 数据文件
JSON 数据文件包含一组对象或数组。COPY 会将每个 JSON 对象或数组加载到目标表中的一行中。与某个行对应的每个对象或数组都必须是独立的根级结构；即，它不能是另一个 JSON 结构的成员。
JSON *对象* 以大括号 (\$1 \$1) 开头和结尾，并包含名称-值对的无序集合。每个成对的名称和值由冒号分隔，而每个名称/值对由逗号分隔。预设情况下，名称-值对中的*对象键*（即名称）必须与表中的对应列的名称匹配。Amazon Redshift 表中的列名称始终小写，因此，匹配的 JSON 字段名称键也必须为小写。如果您的列名称与 JSON 键不匹配，请使用 [JSONPaths 文件](#copy-json-jsonpaths) 将列显式映射到键。
JSON 对象中的顺序不重要。与列名称不匹配的任何名称都将被忽略。下面显示了一个简单 JSON 对象的结构。
```
{
"column1": "value1",
"column2": value2,
"notacolumn" : "ignore this value"
}
```
JSON *数组* 以中括号 ([]) 开头和结尾，并包含由逗号分隔的值的有序集合。如果您的数据文件使用了数组，则必须指定 JSONPaths 文件以将值与列匹配。下面显示了一个简单 JSON 数组的结构。
```
["value1", value2]
```
JSON 必须格式正确。例如，对象或数组不能用逗号或除空格以外的任何其他字符分隔。字符串必须括在双引号字符中。引号字符必须是简单引号 (0x22)，而不能是倾斜引号或“智能”引号。
单个 JSON 对象或数组（包括大括号或中括号）的最大大小为 4 MB。这与最大行大小不同。如果超过了单个 JSON 对象或数组的最大大小，则即使生成的行大小未达到 4 MB 的行大小限制，COPY 命令也会失败。
在计算行大小时，Amazon Redshift 在内部对竖线字符 ( \$1 ) 计为两个字符。如果您的输入数据中包含大量竖线字符，则即使对象大小小于 4 MB，行大小也可能超过 4 MB。
COPY 会将 `\n` 作为换行符加载并且会将 `\t` 作为制表符加载。要加载反斜杠，请使用反斜杠 ( `\\` ) 对其进行转义。
COPY 将在指定的 JSON 源中搜索格式正确且有效的 JSON 对象或数组。如果 COPY 在找到可用的 JSON 结构之前遇到任何非空格字符，或在有效的 JSON 对象或数组之间遇到此类字符，COPY 将为每个实例返回错误。这些错误将计入 MAXERROR 错误计数。当错误计数等于或超过 MAXERROR 时，COPY 将失败。
对于每个错误，Amazon Redshift 都会在 STL\$1LOAD\$1ERRORS 系统表中记录一行。LINE\$1NUMBER 列将记录导致错误的 JSON 对象的最后一行。
如果指定了 IGNOREHEADER，COPY 将忽略 JSON 数据中指定数量的行。JSON 数据中的换行符始终计入到 IGNOREHEADER 计算中。
默认情况下，COPY 将空字符串作为空字段加载。如果指定了 EMPTYASNULL，COPY 会将 CHAR 和 VARCHAR 字段的空字符串作为 NULL 加载。其他数据类型（如 INT）的空字符串始终作为 NULL 加载。
不支持将以下选项与 JSON 一起使用：
+ CSV
+ DELIMITER
+ ESCAPE
+ FILLRECORD
+ FIXEDWIDTH
+ IGNOREBLANKLINES
+ NULL AS
+ READRATIO
+ REMOVEQUOTES
有关更多信息，请参阅 [从 JSON 格式数据执行的 COPY 操作](copy-usage_notes-copy-from-json.md)。有关 JSON 数据结构的更多信息，请转到 [www.json.org](https://www.json.org/)。
## JSONPaths 文件
如果您正在从 JSON 格式的源数据或 Avro 源数据加载，则在预设情况下，COPY 会将源数据中的第一层数据元素映射到目标表中的列。它的操作方式是通过将名称-值对中的每个名称（即对象键）与目标表中的列的名称匹配。
如果您的列名称与对象键不匹配，或要映射到数据层次结构中的更深层次，则可以使用 JSONPaths 文件将 JSON 或 Avro 数据元素显式映射到列。JSONPaths 文件通过匹配目标表或列列表中的列顺序来将 JSON 数据元素映射到列。
JSONPaths 文件只能包含一个 JSON 对象（非数组）。JSON 对象是一个名称-值对。*对象键*（即名称-值对的名称）必须为 `"jsonpaths"`。名称-值对中的*值* 是一组 *JSONPath 表达式*。每个 JSONPath 表达式都引用 JSON 数据层次结构或 Avro schema 中的一个元素，这与 XPath 表达式引用 XML 文档中的元素相似。有关更多信息，请参阅 [JSONPath 表达式](#copy-json-jsonpath-expressions)。
要使用 JSONPaths 文件，请将 JSON 或 AVRO 关键字添加到 COPY 命令。使用以下格式指定 JSONPath 文件的 S3 桶名称和对象路径。
```
COPY tablename
FROM 'data_source'
CREDENTIALS 'credentials-args'
FORMAT AS { AVRO | JSON } 's3://jsonpaths_file';
```
`s3://jsonpaths_file` 参数必须是显式引用单个文件（如 `'s3://amzn-s3-demo-bucket/jsonpaths.txt'`）的 Amazon S3 对象键。它不能是键前缀。
在某些情况下，如果您从 Amazon S3 加载，由 `jsonpaths_file` 指定的文件的前缀与由 `copy_from_s3_objectpath` 为数据文件指定的路径的前缀相同。如果是这样，COPY 会将 JSONPaths 文件作为数据文件读取并返回错误。例如，假设您的数据文件使用对象路径 `s3://amzn-s3-demo-bucket/my_data.json`，并且您的 JSONPaths 文件是 `s3://amzn-s3-demo-bucket/my_data.jsonpaths`。在这种情况下，COPY 会尝试加载 `my_data.jsonpaths` 作为数据文件。
如果键名称是除 `"jsonpaths"` 以外的任何字符串，则 COPY 命令不会返回错误，但会忽略 *jsonpaths\$1file* 并改为使用 `'auto'` 参数。
如果出现以下任一情况，COPY 命令将失败：
+ JSON 格式不正确。
+ 存在多个 JSON 对象。
+ 对象外部存在除空格以外的任何字符。
+ 数组元素是一个空字符串或者不是一个字符串。
MAXERROR 不适用于 JSONPaths 文件。
即使指定了 [ENCRYPTED](copy-parameters-data-source-s3.md#copy-encrypted) 选项，也不得加密 JSONPaths 文件。
有关更多信息，请参阅 [从 JSON 格式数据执行的 COPY 操作](copy-usage_notes-copy-from-json.md)。
## JSONPath 表达式
JSONPaths 文件使用 JSONPath 表达式将数据字段映射到目标列。每个 JSONPath 表达式对应于 Amazon Redshift 目标表中的一个列。JSONPath 数组元素的顺序必须与目标表或列列表（如果使用了列列表）中列的顺序一致。
如上所示，字段名称和值均需要使用双引号字符。引号字符必须是简单引号 (0x22)，而不能是倾斜引号或“智能”引号。
如果 JSONPath 表达式引用的对象元素在 JSON 数据中找不到，则 COPY 将尝试加载 NULL 值。如果引用的对象的格式不正确，则 COPY 将返回加载错误。
如果 JSONPath 表达式引用的数组元素在 JSON 或 Avro 数据中找不到，则 COPY 将失败并返回以下错误：`Invalid JSONPath format: Not an array or index out of range.`请从 JSONPaths 中删除在源数据中不存在的所有数组元素，并确认源数据中数组的格式正确。
JSONPath 表达式可使用括号表示法或点表示法，但不能将两者结合使用。以下示例显示了使用括号表示法的 JSONPath 表达式。
```
{
"jsonpaths": [
"$['venuename']",
"$['venuecity']",
"$['venuestate']",
"$['venueseats']"
]
}
```
以下示例显示了使用点表示法的 JSONPath 表达式。
```
{
"jsonpaths": [
"$.venuename",
"$.venuecity",
"$.venuestate",
"$.venueseats"
]
}
```
在 Amazon Redshift COPY 语法的上下文中，JSONPath 表达式必须指定 JSON 或 Avro 分层数据结构中单个名称元素的显式路径。Amazon Redshift 不支持可能解析为不确定路径或多个名称元素的任何 JSONPath 元素（如通配符或筛选表达式）。
有关更多信息，请参阅 [从 JSON 格式数据执行的 COPY 操作](copy-usage_notes-copy-from-json.md)。
## 将 JSONPaths 与 Avro 数据一起使用
以下示例显示了具有多个层次 Avro schema。
```
{
"name": "person",
"type": "record",
"fields": [
{"name": "id", "type": "int"},
{"name": "guid", "type": "string"},
{"name": "isActive", "type": "boolean"},
{"name": "age", "type": "int"},
{"name": "name", "type": "string"},
{"name": "address", "type": "string"},
{"name": "latitude", "type": "double"},
{"name": "longitude", "type": "double"},
{
"name": "tags",
"type": {
"type" : "array",
"name" : "inner_tags",
"items" : "string"
}
},
{
"name": "friends",
"type": {
"type" : "array",
"name" : "inner_friends",
"items" : {
"name" : "friends_record",
"type" : "record",
"fields" : [
{"name" : "id", "type" : "int"},
{"name" : "name", "type" : "string"}
]
}
}
},
{"name": "randomArrayItem", "type": "string"}
]
}
```
以下示例显示了使用 AvroPath 表达式引用前面的 schema 的 JSONPaths 文件。
```
{
"jsonpaths": [
"$.id",
"$.guid",
"$.address",
"$.friends[0].id"
]
}
```
JSONPaths 示例包含以下元素：
jsonpaths
包含 AvroPath 表达式的 JSON 对象的名称。
[ … ]
方括号将包含路径元素的 JSON 数组括起。
\$1
美元符号表示 Avro schema 中的根元素，即 `"fields"` 数组。
"\$1.id",
AvroPath 表达式的目标。在此实例中，目标是 `"fields"` 数组中名为 `"id"` 的元素。表达式用逗号分隔。
"\$1.friends[0].id"
方括号表示数组索引。JSONPath 表达式使用从零开始的索引，因此该表达式引用 `"friends"` 数组中名为 `"id"` 的第一个元素。
Avro schema 语法需要使用*内部字段* 来定义记录和数组数据类型的结构。AvroPath 表达式将会忽略内部字段。例如，字段 `"friends"` 定义了一个名为 `"inner_friends"` 的数组，该数组又定义了一个名为 `"friends_record"` 的记录。要引用字段 `"id"` 的 AvroPath 表达式可忽略额外字段以直接引用目标字段。以下 AvroPath 表达式引用了两个属于 `"friends"` 数组的字段。
```
"$.friends[0].id"
"$.friends[0].name"
```
## 列式数据格式参数
除标准数据格式以外，COPY 支持 Amazon S3 中有关 COPY 的以下列式数据格式。支持列式中的 COPY，其中带有特定限制。有关更多信息，请参阅 [从列式数据格式中执行 COPY 操作](copy-usage_notes-copy-from-columnar.md)。
ORC
从使用优化的行列式 (ORC) 文件格式的文件中加载数据。
PARQUET
从使用 Parquet 文件格式的文件中加载数据。
# 文件压缩参数
您可以通过指定以下参数来从压缩的数据文件加载。文件压缩参数
BZIP2
一个值，用于指定输入文件采用压缩 bzip2 格式（.bz2 文件）。COPY 操作将读取每个压缩文件并在加载时解压数据。
GZIP
一个值，用于指定输入文件采用压缩 gzip 格式（.gz 文件）。COPY 操作将读取每个压缩文件并在加载时解压数据。
LZOP
一个值，用于指定输入文件采用压缩 lzop 格式（.lzo 文件）。COPY 操作将读取每个压缩文件并在加载时解压数据。
COPY 不支持使用 lzop *--filter* 选项压缩的文件。
ZSTD
一个值，用于指定输入文件采用压缩 Zstandard 格式（.zst 文件）。COPY 操作将读取每个压缩文件并在加载时解压数据。
只有从 Amazon S3 进行 COPY 操作时，才支持 ZSTD。
# 数据转换参数
在加载表时，COPY 会尝试将源数据中的字符串隐式转换为目标列的数据类型。如果您需要指定不同于默认行为的转换，或者默认转换会产生错误，则可以通过指定以下参数来管理数据转换。有关这些参数语法的更多信息，请参阅 [COPY 语法](https://docs.aws.amazon.com/redshift/latest/dg/r_COPY.html#r_COPY-syntax)。
+ [ACCEPTANYDATE](#copy-acceptanydate)
+ [ACCEPTINVCHARS](#copy-acceptinvchars)
+ [BLANKSASNULL](#copy-blanksasnull)
+ [DATEFORMAT](#copy-dateformat)
+ [EMPTYASNULL](#copy-emptyasnull)
+ [ENCODING](#copy-encoding)
+ [ESCAPE](#copy-escape)
+ [EXPLICIT_IDS](#copy-explicit-ids)
+ [FILLRECORD](#copy-fillrecord)
+ [IGNOREBLANKLINES](#copy-ignoreblanklines)
+ [IGNOREHEADER](#copy-ignoreheader)
+ [NULL AS](#copy-null-as)
+ [REMOVEQUOTES](#copy-removequotes)
+ [ROUNDEC](#copy-roundec)
+ [TIMEFORMAT](#copy-timeformat)
+ [TRIMBLANKS](#copy-trimblanks)
+ [TRUNCATECOLUMNS](#copy-truncatecolumns) 数据转换参数
ACCEPTANYDATE
允许加载包括无效格式（如 `00/00/00 00:00:00`）在内的任何日期格式，而不生成错误。此参数仅适用于 TIMESTAMP 和 DATE 列。始终将 ACCEPTANYDATE 与 DATEFORMAT 参数结合使用。如果数据的日期格式与 DATEFORMAT 规范不匹配，则 Amazon Redshift 会将 NULL 值插入该字段中。
ACCEPTINVCHARS [AS] ['*replacement\$1char*']
允许将数据加载到 VARCHAR 列中，即使数据包含无效的 UTF-8 字符。如果指定 ACCEPTINVCHARS，则 COPY 会将每个无效的 UTF-8 字符替换为长度相等且包含由 *replacement\$1char* 指定的字符的字符串。例如，如果替换字符为“`^`”，则将使用“`^^^`”替换无效的三字节字符。
替换字符可以是除 NULL 之外的任何 ASCII 字符。默认值为一个问号 (?)。有关无效的 UTF-8 字符的信息，请参阅[多字节字符加载错误](multi-byte-character-load-errors.md)。
COPY 将返回包含无效 UTF-8 字符的行的数量，并将为每个受影响的行在 [STL\$1REPLACEMENTS](r_STL_REPLACEMENTS.md) 系统表中添加一个条目，每个节点切片最多有 100 行。还将替换其他无效的 UTF-8 字符，但不会记录这些替换事件。
如果未指定 ACCEPTINVCHARS，则 COPY 在遇到无效 UTF-8 字符时将返回错误。
ACCEPTINVCHARS 仅对 VARCHAR 列有效。
BLANKSASNULL
将仅包含空格字符的空白字段作为 NULL 加载。此选项仅适用于 CHAR 和 VARCHAR 列。其他数据类型（如 INT）的空白字段始终作为 NULL 加载。例如，包含三个连续的空格字符（并且无其他字符）的字符串将作为 NULL 加载。如果不使用此选项，则默认行为是按原样加载空白字符。
DATEFORMAT [AS] \$1'*dateformat\$1string*' \$1 'auto' \$1
如果未指定 DATEFORMAT，则默认格式为 `'YYYY-MM-DD'`。例如，一种有效的替代格式为 `'MM-DD-YYYY'`。
如果 COPY 命令未识别日期或时间值的格式，或者日期或时间值使用不同的格式，请将 `'auto'` 参数与 DATEFORMAT 或 TIMEFORMAT 参数结合使用。在使用 DATEFORMAT 和 TIMEFORMAT 字符串时，`'auto'` 参数将识别一些不受支持的格式。`'auto'` 的关键字区分大小写。有关更多信息，请参阅 [在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别](automatic-recognition.md)。
日期格式可包含时间信息（小时、分钟、秒），但此信息将被忽略。AS 关键字是可选的。有关更多信息，请参阅 [DATEFORMAT 和 TIMEFORMAT 字符串示例](r_DATEFORMAT_and_TIMEFORMAT_strings.md)。
EMPTYASNULL
指示 Amazon Redshift 应将空 CHAR 和 VARCHAR 字段作为 NULL 加载。其他数据类型（如 INT）的空字段始终作为 NULL 加载。当数据包含两个连续的分隔符且分隔符之间没有字符时，将出现空字段。EMPTYASNULL 和 NULL AS ''（空字符串）将产生相同的行为。
ENCODING [AS] *file\$1encoding*
指定加载数据的编码类型。COPY 命令在加载过程中将数据从指定的编码转换为 UTF-8。
*file\$1encoding* 的有效值如下所示：
+ `UTF8`
+ `UTF16`
+ `UTF16LE`
+ `UTF16BE`
+ `ISO88591`
默认为 `UTF8`。
源文件名必须使用 UTF-8 编码。
下列文件必须使用 UTF-8 编码，即使为加载数据指定了不同的编码：
+ 清单文件
+ JSONPaths 文件
随下列参数提供的参数字符串必须使用 UTF-8：
+ FIXEDWIDTH '*fixedwidth\$1spec*'
+ ACCEPTINVCHARS '*replacement\$1char*'
+ DATEFORMAT '*dateformat\$1string*'
+ TIMEFORMAT '*timeformat\$1string*'
+ NULL AS '*null\$1string*'
固定宽度的数据文件必须使用 UTF-8 编码。字段宽度基于字符数，而不是字节数。
所有加载数据必须使用指定编码。如果 COPY 遇到不同的编码，将跳过文件并返回错误。
如果您指定 `UTF16`，则您的数据必须具有字节顺序标记 (BOM)。如果您知道您的 UTF-16 数据是否为 little-endian (LE) 或 big-endian (BE)，则不管是否存在 BOM，均可使用 `UTF16LE` 或 `UTF16BE`。
要使用 ISO-8859-1 编码，请指定 `ISO88591`。有关更多信息，请参阅 *Wikipedia* 中的 [ISO/IEC 8859-1](https://en.wikipedia.org/wiki/ISO/IEC_8859-1)。
ESCAPE
指定此参数后，输入数据中的反斜杠字符 (`\`) 将被视为转义字符。紧跟在反斜杠字符后面的字符将作为当前列值的一部分加载到表中，即使它是通常用作特殊用途的字符。例如，您可使用此参数转义分隔符字符、引号、嵌入的换行符或转义字符本身，前提是这些字符中的任何字符是列值的合法部分。
如果您指定 ESCAPE 参数与 REMOVEQUOTES 参数的组合，则可转义并保留可能会被删除的引号（`'` 或 `"`）。默认 null 字符串 `\N` 按原样工作，但也可在输入数据中转义为 `\\N`。只要您未使用 NULL AS 参数指定替换 null 字符串，`\N` 和 `\\N` 就会产生相同的结果。
控制字符 `0x00` (NUL) 无法转义，应从输入数据中删除或进行转换。此字符将被视为记录结束 (EOR) 标记，并导致记录的剩余部分被截断。
您无法对 FIXEDWIDTH 加载使用 ESCAPE 参数，并且无法指定转义字符本身；转义字符始终为反斜杠字符。此外，您必须确保输入数据在合适的位置包含转义字符。
下面是在指定 ESCAPE 参数的情况下的输入数据和产生的加载数据的一些示例。第 4 行的结果假设还指定了 REMOVEQUOTES 参数。输入数据包含两个用竖线分隔的字段：
```
1|The quick brown fox\[newline]
jumped over the lazy dog.
2| A\\B\\C
3| A \| B \| C
4| 'A Midsummer Night\'s Dream'
```
加载到第 2 列的数据看上去与下面类似：
```
The quick brown fox
jumped over the lazy dog.
A\B\C
A|B|C
A Midsummer Night's Dream
```
对加载的输入数据应用转义字符是用户的责任。此要求的一个例外情况是在您重新加载之前使用 ESCAPE 参数卸载的数据时。在此情况下，数据将已经包含必需的转义字符。
ESCAPE 参数不会解释 octal、hex、Unicode 或其他转义序列表示法。例如，如果您的源数据包含 octal 换行符值 (`\012`) 并且您尝试使用 ESCAPE 参数加载此数据，则 Amazon Redshift 会将值 `012` 加载到表中并且不会将此值解释为要转义的换行符。
为了转义源自 Microsoft Windows 平台的数据中的换行符，您可能需要使用两个转义字符：一个用于回车，一个用于换行。您也可以在加载文件（例如，通过使用 dos2unix 实用工具）之前删除回车符。
EXPLICIT\$1IDS
如果要将表中自动生成的值替换为源数据文件中的显式值，请对具有 IDENTITY 列的表使用 EXPLICIT\$1IDS。如果命令包含一个列列表，则该列表必须包含 IDENTITY 列才能使用此参数。EXPLICIT\$1IDS 值的数据格式必须与 CREATE TABLE 定义指定的 IDENTITY 格式匹配。
在对表运行带 EXPLICIT\$1IDS 选项的 COPY 命令时，Amazon Redshift 不会检查表中 IDENTITY 列的唯一性。
如果某个列使用 GENERATED BY DEFAULT AS IDENTITY 进行定义，则可以复制该列。使用您提供的值生成或更新值。EXPLICIT\$1IDS 选项不是必需项。COPY 不会更新身份高级别水印。
有关使用 EXPLICIT\$1IDS 的 COPY 命令的示例，请参阅[加载具有显式的 IDENTITY 列值的 VENUE](r_COPY_command_examples.md#r_COPY_command_examples-load-venue-with-explicit-values-for-an-identity-column)。
FILLRECORD
当一些记录的末尾缺少相邻列时，允许加载数据文件。将缺少的列加载为 NULL。对于文本和 CSV 格式，如果缺少的是 VARCHAR 列，则会加载零长度字符串而非 NULL。要从文本和 CSV 将 NULL 加载到 VARCHAR 列，请指定 EMPTYASNULL 关键字。仅当列定义允许 NULL 时，NULL 替换才会工作。
例如，如果表定义包含 4 个可以为 null 的 CHAR 列，并且记录包含值 `apple, orange, banana, mango`，则 COPY 命令可能加载并填充仅包含 `apple, orange` 值的记录。缺少的 CHAR 值将作为 NULL 值加载。
IGNOREBLANKLINES
忽略数据文件中仅包含换行符的空行并且不尝试加载它们。
IGNOREHEADER [ AS ] *number\$1rows*
将指定的 *number\$1rows* 视为文件标题并且不加载它们。使用 IGNOREHEADER 跳过并行加载的所有文件中的文件标题。
NULL AS '*null\$1string*'
加载将 *null\$1string* 匹配为 NULL 的字段，其中 *null\$1string* 可以是任何字符串。如果您的数据包含 null 终止符（也称为 NUL (UTF-8 0000) 或二进制零 (0x000)），则 COPY 会将其视为任何其他字符。例如，包含 '1' \$1\$1 NUL \$1\$1 '2' 的记录被复制为长度为 3 个字节的字符串。如果字段仅包含 NUL，您可使用 NULL AS 通过指定 `'\0'` 或 `'\000'` 来将 null 终止符替换为 NULL，例如，`NULL AS '\0'` 或 `NULL AS '\000'`。如果指定包含以 NUL 和 NULL AS 结尾的字符串的字段，则将在末尾处插入 NUL。请勿将“\$1n”（换行符）用于 *null\$1string* 值。Amazon Redshift 将保留“\$1n”以用作行分隔符。默认 *null\$1string* 为 `'\N`'。
如果您尝试将 null 加载到定义为 NOT NULL 的列中，则 COPY 命令将失败。
REMOVEQUOTES
删除传入数据中的字符串周围的引号。将保留引号中的所有字符（包括分隔符）。如果字符串具有开始单引号或双引号但没有对应的结束引号，则 COPY 命令将无法加载相应行并返回错误。下表显示了包含引号的字符串和最终加载值的一些简单示例。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/copy-parameters-data-conversion.html)
ROUNDEC
当输入值的小数位数超出列的小数位数时，会将数值向上取整。默认情况下，COPY 将在必要时截断值以匹配列的小数位数。例如，如果将值 `20.259` 加载到 DECIMAL(8,2) 列中，则 COPY 默认情况下会将此值截断为 `20.25`。如果指定 ROUNDEC，则 COPY 会将值取整为 `20.26`。INSERT 命令始终在必要时将值取整以匹配列的小数位数，因此包含 ROUNDEC 参数的 COPY 命令的行为方式与 INSERT 命令相同。
TIMEFORMAT [AS] \$1'*timeformat\$1string*' \$1 'auto' \$1 'epochsecs' \$1 'epochmillisecs' \$1
指定时间格式。如果未指定 TIMEFORMAT，则默认格式为 `YYYY-MM-DD HH:MI:SS`（对于 TIMESTAMP 列）或 `YYYY-MM-DD HH:MI:SSOF`（对于 TIMESTAMPTZ 列），其中 `OF` 是与协调世界时 (UTC) 的时差。您不能在 *timeformat\$1string* 中包括时区标识符。要加载格式与默认格式不同的 TIMESTAMPTZ 数据，请指定“自动”；有关更多信息，请参阅 [在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别](automatic-recognition.md)。有关 *timeformat\$1string* 的更多信息，请参阅 [DATEFORMAT 和 TIMEFORMAT 字符串示例](r_DATEFORMAT_and_TIMEFORMAT_strings.md)。
在使用 DATEFORMAT 和 TIMEFORMAT 字符串时，`'auto'` 参数将识别一些不受支持的格式。如果 COPY 命令未识别日期或时间值的格式，或者日期和时间值使用不同的格式，请将 `'auto'` 参数与 DATEFORMAT 或 TIMEFORMAT 参数结合使用。有关更多信息，请参阅 [在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别](automatic-recognition.md)。
如果源数据以纪元时间（自 1970 年 1 月 1 日 00:00:00 UTC 以来的秒数或微秒数）表示，请指定 `'epochsecs'` 或 `'epochmillisecs'`。
`'auto'`、`'epochsecs'` 和 `'epochmillisecs'` 关键字区分大小写。
AS 关键字是可选的。
TRIMBLANKS
删除 VARCHAR 字符串的尾部空格字符。此参数仅适用于具有 VARCHAR 数据类型的列。
TRUNCATECOLUMNS
将列中的数据截断为合适的字符数以符合列规范。仅适用于具有 VARCHAR 或 CHAR 数据类型的列以及大小为 4 MB 或以下的行。
# 数据加载操作
通过指定以下参数来管理加载操作的默认行为，以进行故障排除或缩短加载时间。
+ [COMPROWS](#copy-comprows)
+ [COMPUPDATE](#copy-compupdate)
+ [IGNOREALLERRORS](#copy-ignoreallerrors)
+ [MAXERROR](#copy-maxerror)
+ [NOLOAD](#copy-noload)
+ [STATUPDATE](#copy-statupdate) 参数
COMPROWS *numrows*
指定要用作压缩分析的样本大小的行数。将对来自每个数据切片的行运行分析。例如，如果指定 `COMPROWS 1000000` (1000000) 且系统总共包含 4 个切片，则将为每个切片读取和分析的行数不超过 250000。
如果未指定 COMPROWS，则每个切片的样本大小默认为 100000。小于每个切片 100000 行这一默认值的 COMPROWS 值将自动升级到此默认值。但是，如果加载的数据量不足以生成有意义的样本，则不会执行自动压缩。
如果 COMPROWS 数量大于输入文件中的行数，则 COPY 命令仍将继续并对所有可用行运行压缩分析。此参数接受的范围介于 1000 到 2147483647 (2,147,483,647) 之间。
COMPUPDATE [ PRESET \$1 \$1 ON \$1 TRUE \$1 \$1 \$1 OFF \$1 FALSE \$1 ]
控制是否在 COPY 期间自动应用压缩编码。
如果 COMPUPDATE 为 PRESET，则在目标表为空时，COPY 命令会为每个列选择压缩编码，即使列已经有除 RAW 之外的编码也不例外。可以替换当前指定的列编码。每个列的编码基于列数据类型。不会对数据进行采样。Amazon Redshift 自动分配压缩编码，如下所示：
+ 为定义为排序键的列分配 RAW 压缩。
+ 为定义为 BOOLEAN、REAL 或 DOUBLE PRECISION 数据类型的列分配 RAW 压缩。
+ 定义为 SMALLINT、INTEGER、BIGINT、DECIMAL、DATE、TIMESTAMP 或 TIMESTAMPTZ 的列分配了 AZ64 压缩。
+ 定义为 CHAR 或 VARCHAR 的列分配了 LZO 压缩。
如果省略了 COMPUPDATE，只有在目标表为空并且您没有为任何列指定编码（而非 RAW）时，COPY 命令才会为每个列选择压缩编码。每个列的编码是由 Amazon Redshift 确定的。不会对数据进行采样。
如果 COMPUPDATE 为 ON（或 TRUE）或者指定 COMPUPDATE 而没有提供选项，在表为空时，COPY 命令将应用自动压缩，即使表列已具有除 RAW 以外的编码。可以替换当前指定的列编码。每个列的编码基于样本数据分析。有关更多信息，请参阅 [使用自动压缩加载表](c_Loading_tables_auto_compress.md)。
在 COMPUPDATE 为 OFF（或 FALSE）时，将禁用自动压缩。不会更改列编码。
有关分析压缩的系统表的信息，请参阅 [STL\$1ANALYZE\$1COMPRESSION](r_STL_ANALYZE_COMPRESSION.md)。
IGNOREALLERRORS
您可以指定此选项来忽略加载操作期间出现的所有错误。
如果您指定了 MAXERROR 选项，则无法指定 IGNOREALLERRORS 选项。不能为列式格式（包括 ORC 和 Parquet）指定 IGNOREALLERRORS 选项。
MAXERROR [AS] *error\$1count*
如果加载操作返回 *error\$1count* 数量的错误或更多错误，加载将失败。如果加载操作返回较少的错误，则将继续并返回指示无法加载的行数的 INFO 消息。使用此参数可允许加载操作在某些行因为格式设置错误或数据中的其他不一致性而未能加载到表中时继续。
如果您希望加载操作在出现第一个错误时就失败，请将此值设置为 `0` 或 `1`。AS 关键字是可选的。MAXERROR 默认值为 `0`，限制值为 `100000`。
由于 Amazon Redshift 的并行处理特性，报告的实际错误数量可能高出指定的 MAXERROR。如果 Amazon Redshift 集群中的任何节点检测到已超出 MAXERROR，则每个节点将报告它遇到的所有错误。
NOLOAD
检查数据文件的有效性，而不用实际加载数据。通过使用 NOLOAD 参数，可以在运行实际数据加载之前，确保数据文件加载而不产生任何错误。将 COPY 与 NOLOAD 参数结合运行将比加载数据要快很多，因为前者仅分析文件。
STATUPDATE [ \$1 ON \$1 TRUE \$1 \$1 \$1 OFF \$1 FALSE \$1 ]
在成功的 COPY 命令结束时，控制对优化器统计数据的自动计算和刷新。默认情况下，如果未使用 STATUPDATE 参数，则将在表最初为空时自动更新统计数据。
将数据插入非空表中将明显更改表的大小，我们建议通过运行 [ANALYZE](r_ANALYZE.md) 命令或使用 STATUPDATE ON 参数来更新统计数据。
使用 STATUPDATE ON（或 TRUE），不管表最初是否为空，都将自动更新统计数据。如果使用 STATUPDATE，则当前用户必须是表所有者或超级用户。如果未指定 STATUPDATE，则仅需要 INSERT 权限。
通过使用 STATUPDATE OFF（或 FALSE），将从不更新统计数据。
有关更多信息，请参阅[分析表](t_Analyzing_tables.md)。
# 按字母顺序排列的参数列表
以下列表提供指向每个 COPY 命令参数（按字母顺序排列）的描述的链接。
+ [ACCEPTANYDATE](copy-parameters-data-conversion.md#copy-acceptanydate)
+ [ACCEPTINVCHARS](copy-parameters-data-conversion.md#copy-acceptinvchars)
+ [ACCESS\$1KEY\$1ID、SECRET\$1ACCESS\$1KEY](copy-parameters-authorization.md#copy-access-key-id-access)
+ [AVRO](copy-parameters-data-format.md#copy-avro)
+ [BLANKSASNULL](copy-parameters-data-conversion.md#copy-blanksasnull)
+ [BZIP2](copy-parameters-file-compression.md#copy-bzip2)
+ [COMPROWS](copy-parameters-data-load.md#copy-comprows)
+ [COMPUPDATE](copy-parameters-data-load.md#copy-compupdate)
+ [CREDENTIALS](copy-parameters-authorization.md#copy-credentials-cred)
+ [CSV](copy-parameters-data-format.md#copy-csv)
+ [DATEFORMAT](copy-parameters-data-conversion.md#copy-dateformat)
+ [DELIMITER](copy-parameters-data-format.md#copy-delimiter)
+ [EMPTYASNULL](copy-parameters-data-conversion.md#copy-emptyasnull)
+ [ENCODING](copy-parameters-data-conversion.md#copy-encoding)
+ [ENCRYPTED](copy-parameters-data-source-s3.md#copy-encrypted)
+ [ESCAPE](copy-parameters-data-conversion.md#copy-escape)
+ [EXPLICIT_IDS](copy-parameters-data-conversion.md#copy-explicit-ids)
+ [FILLRECORD](copy-parameters-data-conversion.md#copy-fillrecord)
+ [FIXEDWIDTH](copy-parameters-data-format.md#copy-fixedwidth)
+ [FORMAT](copy-parameters-data-format.md#copy-format)
+ [FROM](copy-parameters-data-source-s3.md#copy-parameters-from)
+ [GZIP](copy-parameters-file-compression.md#copy-gzip)
+ [IAM\$1ROLE](copy-parameters-authorization.md#copy-iam-role-iam)
+ [IGNOREALLERRORS](copy-parameters-data-load.md#copy-ignoreallerrors)
+ [IGNOREBLANKLINES](copy-parameters-data-conversion.md#copy-ignoreblanklines)
+ [IGNOREHEADER](copy-parameters-data-conversion.md#copy-ignoreheader)
+ [JSON format for COPY](copy-parameters-data-format.md#copy-json)
+ [LZOP](copy-parameters-file-compression.md#copy-lzop)
+ [MANIFEST](copy-parameters-data-source-s3.md#copy-manifest)
+ [MASTER_SYMMETRIC_KEY](copy-parameters-data-source-s3.md#copy-master-symmetric-key)
+ [MAXERROR](copy-parameters-data-load.md#copy-maxerror)
+ [NOLOAD](copy-parameters-data-load.md#copy-noload)
+ [NULL AS](copy-parameters-data-conversion.md#copy-null-as)
+ [READRATIO](copy-parameters-data-source-dynamodb.md#copy-readratio)
+ [REGION](copy-parameters-data-source-s3.md#copy-region)
+ [REMOVEQUOTES](copy-parameters-data-conversion.md#copy-removequotes)
+ [ROUNDEC](copy-parameters-data-conversion.md#copy-roundec)
+ [SESSION\$1TOKEN](copy-parameters-authorization.md#copy-token)
+ [SHAPEFILE](copy-parameters-data-format.md#copy-shapefile)
+ [SSH](copy-parameters-data-source-ssh.md#copy-ssh)
+ [STATUPDATE](copy-parameters-data-load.md#copy-statupdate)
+ [TIMEFORMAT](copy-parameters-data-conversion.md#copy-timeformat)
+ [TRIMBLANKS](copy-parameters-data-conversion.md#copy-trimblanks)
+ [TRUNCATECOLUMNS](copy-parameters-data-conversion.md#copy-truncatecolumns)
+ [ZSTD](copy-parameters-file-compression.md#copy-zstd)
# 使用说明
**Topics**
+ [访问其他 AWS 资源的权限](copy-usage_notes-access-permissions.md)
+ [将 COPY 与 Amazon S3 接入点别名一起使用](copy-usage_notes-s3-access-point-alias.md)
+ [从 Amazon S3 中加载多字节数据](copy-usage_notes-multi-byte.md)
+ [加载 GEOMETRY 或 GEOGRAPHY 数据类型的列](copy-usage_notes-spatial-data.md)
+ [加载 HLLSKETCH 数据类型](copy-usage_notes-hll.md)
+ [加载 VARBYTE 数据类型的列](copy-usage-varbyte.md)
+ [在读取多个文件时出现错误](copy-usage_notes-multiple-files.md)
+ [从 JSON 格式数据执行的 COPY 操作](copy-usage_notes-copy-from-json.md)
+ [从列式数据格式中执行 COPY 操作](copy-usage_notes-copy-from-columnar.md)
+ [DATEFORMAT 和 TIMEFORMAT 字符串](r_DATEFORMAT_and_TIMEFORMAT_strings.md)
+ [在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别](automatic-recognition.md)
# 访问其他 AWS 资源的权限
要在您的集群和其他 AWS 资源（如 Amazon S3 、Amazon DynamoDB、Amazon EMR 或 Amazon EC2）之间移动数据，您的集群必须具有访问相应资源和执行所需操作的权限。例如，要从 Amazon S3 加载数据，COPY 必须具有对桶的 LIST 访问权限以及对桶对象的 GET 访问权限。有关最低权限的更多信息，请参阅 [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](#copy-usage_notes-iam-permissions)。
要获取访问资源的授权，您的集群必须经过身份验证。您可以选择以下身份验证方法之一：
+ [基于角色的访问控制](#copy-usage_notes-access-role-based) – 对于基于角色的访问控制，您指定您的集群用于身份验证和授权的 AWS Identity and Access Management (IAM) 角色。为了保护您的 AWS 凭证和敏感数据，我们强烈建议使用基于角色的身份验证。
+ [基于密钥的访问控制](#copy-usage_notes-access-key-based) – 对于基于密钥的访问控制，您以纯文本形式为用户提供 AWS 访问凭证（访问密钥 ID 和秘密访问密钥）。
## 基于角色的访问控制
利用基于角色的访问控制，您的集群将代表您临时代入 IAM 角色。然后，基于对角色的授权，您的集群可访问所需的 AWS 资源。
创建 IAM *角色*类似于向用户授予权限，因为它是一个 AWS 身份，具有确定该身份在 AWS 中可执行和不可执行的操作的权限策略。但是，任何实体都可以根据需要代入某个角色，角色并不是唯一地与某个用户关联。此外，角色没有任何关联的凭证（密码或访问密钥）。相反，如果将角色与集群关联，则会动态创建访问密钥并将其提供给集群。
我们建议使用基于角色的访问控制，因为除了保护您的 AWS 凭证之外，它还将提供对 AWS 资源和敏感用户数据的更安全、精细的访问控制。
基于角色的身份验证具有以下优点：
+ 您可以使用 AWS 标准 IAM 工具定义 IAM 角色并将该角色与多个集群关联。当您修改某个角色的访问策略时，更改将自动应用于使用该角色的所有集群。
+ 您可定义为特定集群和数据库用户授予对特定 AWS 资源和操作的访问权限的精细 IAM 策略。
+ 您的集群将在运行时获取临时会话凭证并按需刷新凭证直到操作完成。如果您使用了基于密钥的临时凭证，并且临时凭证在操作完成前到期，操作将失败。
+ 您的访问密钥 ID 和秘密访问密钥 ID 不会在 SQL 代码中存储或传输。
要使用基于角色的访问控制，您必须先使用 Amazon Redshift 服务角色类型创建 IAM 角色，然后将此角色附加到您的集群。此角色至少必须具有 [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](#copy-usage_notes-iam-permissions)中列出的权限。有关创建 IAM 角色并将其附加到集群的步骤，请参阅《Amazon Redshift 管理指南》**中的[授权 Amazon Redshift 代表您访问其它 AWS 服务](https://docs.aws.amazon.com/redshift/latest/mgmt/authorizing-redshift-service.html)。
通过使用 Amazon Redshift 管理控制台、CLI 或 API，您可将角色添加到集群或查看与集群关联的角色。有关更多信息，请参阅《Amazon Redshift 管理指南》**中的[将 IAM 角色与集群关联](https://docs.aws.amazon.com/redshift/latest/mgmt/copy-unload-iam-role.html)。
当您创建 IAM 角色时，IAM 将返回该角色的 Amazon 资源名称 (ARN)。要指定 IAM 角色，请利用 [使用 IAM\$1ROLE 参数](copy-parameters-authorization.md#copy-iam-role) 参数或 [使用 CREDENTIALS 参数](copy-parameters-authorization.md#copy-credentials) 参数提供角色 ARN。
例如，假设以下角色已附加到集群。
```
"IamRoleArn": "arn:aws:iam::0123456789012:role/MyRedshiftRole"
```
以下 COPY 命令示例使用 IAM\$1ROLE 参数，其 ARN 在上一示例中用于身份验证和访问 Amazon S3。
```
copy customer from 's3://amzn-s3-demo-bucket/mydata'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
以下 COPY 命令示例使用 CREDENTIALS 参数指定 IAM 角色。
```
copy customer from 's3://amzn-s3-demo-bucket/mydata'
credentials
'aws_iam_role=arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
此外，超级用户还可以向数据库用户和组授予 ASSUMEROLE 权限，以便为 COPY 操作提供对角色的访问权限。有关信息，请参阅 [GRANT](r_GRANT.md)。
## 基于密钥的访问控制
利用基于密钥的访问控制，您将为获权访问包含数据的 AWS 资源的 IAM 用户提供访问密钥 ID 和秘密访问密钥。您可以结合使用 [使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 参数](copy-parameters-authorization.md#copy-access-key-id) 参数或使用 [使用 CREDENTIALS 参数](copy-parameters-authorization.md#copy-credentials) 参数。
**注意**
我们强烈建议使用 IAM 角色进行身份验证而不是提供纯文本访问密钥 ID 和秘密访问密钥。如果您选择基于密钥的访问控制，则不要使用 AWS 账户（根）凭证。应始终创建 IAM 用户并提供该用户的访问密钥 ID 和秘密访问密钥。有关创建 IAM 用户的步骤，请参阅[在您的 AWS 账户中创建 IAM 用户](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)。
要使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 进行身份验证，请使用授权用户的访问密钥 ID 和完整的秘密访问密钥替换 ** 和 **，如下所示。
```
ACCESS_KEY_ID ''
SECRET_ACCESS_KEY '';
```
要使用 CREDENTIALS 参数进行身份验证，请使用授权用户的访问密钥 ID 和完整的秘密访问密钥替换 ** 和 **，如下所示。
```
CREDENTIALS
'aws_access_key_id=;aws_secret_access_key=';
```
IAM 用户必须至少具有 [COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限](#copy-usage_notes-iam-permissions) 中列出的权限。
### 临时安全凭证
如果您使用基于密钥的访问控制，则可通过使用临时安全凭证进一步限制用户对您的数据具有的访问权限。基于角色的身份验证将自动使用临时凭证。
**注意**
我们强烈建议您使用 [role-based access control](#copy-usage_notes-access-role-based.phrase)，而不要创建临时凭证并提供纯文本形式的访问密钥 ID 和秘密访问密钥。基于角色的访问控制将自动使用临时凭证。
临时安全证书可增强安全性，因为它们时效短，过期后无法重复使用。使用令牌生成的访问密钥 ID 和秘密访问密钥无法脱离令牌使用，具有这些临时安全凭证的用户仅可以在凭证未过期前访问您的资源。
要为用户授予对您的资源的临时访问权限，请调用 AWS Security Token Service (AWS STS) API 操作。AWS STS API 操作将返回临时安全凭证，其中包括一个安全令牌、一个访问密钥 ID 和一个秘密访问密钥。您为需要临时访问您的资源的用户颁发临时安全凭证。这些用户可以是现有的 IAM 用户，也可以是非 AWS 用户。有关创建临时安全凭证的更多信息，请参阅《IAM 用户指南》中的[使用临时安全凭证](https://docs.aws.amazon.com/STS/latest/UsingSTS/Welcome.html)。
您可以将 [使用 ACCESS\$1KEY\$1ID 和 SECRET\$1ACCESS\$1KEY 参数](copy-parameters-authorization.md#copy-access-key-id) 参数与 [SESSION\$1TOKEN](copy-parameters-authorization.md#copy-token) 参数或 [使用 CREDENTIALS 参数](copy-parameters-authorization.md#copy-credentials) 参数配合使用。您还必须提供随令牌一起提供的访问密钥 ID 和秘密访问密钥。
要使用 ACCESS\$1KEY\$1ID、SECRET\$1ACCESS\$1KEY 和 SESSION\$1TOKEN 进行身份验证，请根据如下所示替换 **、** 和 **。
```
ACCESS_KEY_ID ''
SECRET_ACCESS_KEY ''
SESSION_TOKEN '';
```
要使用 CREDENTIALS 进行身份验证，请在凭证字符串中包括 `session_token=`，如下所示。
```
CREDENTIALS
'aws_access_key_id=;aws_secret_access_key=;session_token=';
```
以下示例为具有临时安全凭证的 COPY 命令。
```
copy table-name
from 's3://objectpath'
access_key_id ''
secret_access_key ''
session_token '';
```
以下示例使用临时凭证和文件加密加载 LISTING 表。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listings_pipe.txt'
access_key_id ''
secret_access_key ''
session_token ''
master_symmetric_key ''
encrypted;
```
以下示例将 CREDENTIALS 参数与临时凭证和文件加密配合使用，加载 LISTING 表。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listings_pipe.txt'
credentials
'aws_access_key_id=;aws_secret_access_key=;session_token=;master_symmetric_key='
encrypted;
```
**重要**
临时安全凭证必须在整个 COPY 或 UNLOAD 操作持续时间有效。如果临时安全凭证在操作过程中过期，相应命令将失败，事务将被回滚。例如，如果临时安全凭证在 15 分钟后过期而 COPY 操作需要一个小时，则 COPY 操作将失败，无法完成。如果您使用基于角色的访问，则会自动刷新临时安全凭证直到操作完成。
## COPY、UNLOAD 和 CREATE LIBRARY 的 IAM 权限
CREDENTIALS 参数引用的 IAM 角色或用户必须至少具有以下权限：
+ 对于从 Amazon S3 执行的 COPY 的操作，这是指对 Amazon S3 桶执行 LIST 以及对正在加载的 Amazon S3 对象以及清单文件（如果已使用）执行 GET 的权限。
+ 对于从 Amazon S3、Amazon EMR 执行 COPY 的操作、以及从使用 JSON 格式数据的远程主机 (SSH) 执行 COPY 的操作，这是指对 Amazon S3 上的 JSONPaths 文件（如果已使用）执行 LIST 和 GET 的权限。
+ 对于从 DynamoDB 执行 COPY 的操作，这是指对所加载的 DynamoDB 表执行 SCAN 和 DESCRIBE 的权限。
+ 对于从 Amazon EMR 集群执行的 COPY 操作，这是指对 Amazon EMR 集群上的 `ListInstances` 操作的权限。
+ 对于向 Amazon S3 执行 UNLOAD 的操作，这是指正在将数据文件卸载到的 Amazon S3 桶的 GET、LIST 和 PUT 权限。
+ 对于从 Amazon S3 执行 CREATE LIBRARY 的操作，这是指对 Amazon S3 桶执行 LIST 以及对正在导入的 Amazon S3 对象执行 GET 的权限。
**注意**
如果您在运行 COPY、UNLOAD 或 CREATE LIBRARY 命令时收到错误消息 `S3ServiceException: Access Denied`，则您的集群对于 Amazon S3 没有适当的访问权限。
您可以通过向附加到集群的 IAM 角色、向用户或向用户所属的组附加 IAM 策略，来管理 IAM 权限。例如，`AmazonS3ReadOnlyAccess` 托管策略可授予对 Amazon S3 资源的 LIST 和 GET 权限。有关 IAM 策略的更多信息，请参阅《IAM 用户指南》**中的[管理 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage.html)。
# 将 COPY 与 Amazon S3 接入点别名一起使用
COPY 支持 Amazon S3 接入点别名。有关更多信息，请参阅《Amazon Simple Storage Service 用户指南》**中的[为您的接入点使用存储桶式别名](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-points-alias.html)。
# 从 Amazon S3 中加载多字节数据
如果您的数据包含非 ASCII 多字节字符（例如中文或西里尔语字符），则必须将该数据加载到 VARCHAR 列。VARCHAR 数据类型支持四字节的 UTF-8 字符，而 CHAR 数据类型仅接受单字节的 ASCII 字符。您不能将五字节或更长的字符加载到 Amazon Redshift 表中。有关更多信息，请参阅 [多字节字符](c_Supported_data_types.md#c_Supported_data_types-multi-byte-characters)。
# 加载 GEOMETRY 或 GEOGRAPHY 数据类型的列
您可以从字符分隔文本文件（如 CSV 文件）中的数据执行对 `GEOMETRY` 或 `GEOGRAPHY` 列的 COPY 操作。数据必须采用已知二进制（WKB 或 EWKB）格式或已知文本（WKT 或 EWKT）格式的十六进制格式，并且符合 COPY 命令的单个输入行的最大大小范围要求。有关更多信息，请参阅 [COPY](r_COPY.md)。
有关如何从 shapefile 加载的信息，请参阅[将 shapefile 加载到 Amazon Redshift](spatial-copy-shapefile.md)。
有关 `GEOMETRY` 或 `GEOGRAPHY` 数据类型的更多信息，请参阅[在 Amazon Redshift 中查询空间数据](geospatial-overview.md)。
# 加载 HLLSKETCH 数据类型
您只能以 Amazon Redshift 支持的稀疏或密集格式复制 HLL 草图。要在 HyperLogLog 草图上使用 COPY 命令，请对密集 HyperLogLog 草图使用 Base64 格式，对稀疏 HyperLogLog 草图使用 JSON 格式。有关更多信息，请参阅 [HyperLogLog 函数](hyperloglog-functions.md)。
以下示例使用 CREATE TABLE 和 COPY 将 CSV 文件中的数据导入到表中。首先，该示例使用 CREATE TABLE 创建表 `t1`。
```
CREATE TABLE t1 (sketch hllsketch, a bigint);
```
然后，它使用 COPY 将 CSV 文件中的数据导入到表 `t1` 中。
```
COPY t1 FROM s3://amzn-s3-demo-bucket/unload/' IAM_ROLE 'arn:aws:iam::0123456789012:role/MyRedshiftRole' NULL AS 'null' CSV;
```
# 加载 VARBYTE 数据类型的列
您可以从 CSV、Parquet 和 ORC 格式的文件加载数据。对于 CSV，从以十六进制表示 VARBYTE 数据的文件中加载数据。你无法使用 `FIXEDWIDTH` 选项加载 VARBYTE 数据。不支持 COPY 的 `ADDQUOTES` 或 `REMOVEQUOTES` 选项。不可将 VARBYTE 列用作分区列。
# 在读取多个文件时出现错误
COPY 命令是原子和事务性的。换言之，甚至在 COPY 命令读取多个文件中的数据时，整个过程也将视为单个事务。如果 COPY 在读取某个文件时遇到错误，则将自动重试直至此过程超时（请参阅[statement\$1timeout](r_statement_timeout.md)），或者如果在较长时间（15 到 30 分钟）内无法从 Amazon S3 下载数据，则将确保一次仅下载一个文件。如果 COPY 命令失败，则将取消整个事务并回滚所有更改。有关处理加载错误的更多信息，请参阅[解决数据加载问题](t_Troubleshooting_load_errors.md)。
在成功启动 COPY 命令后，此命令不会在会话终止（例如客户端断开）时失败。但是，如果 COPY 命令位于因会话终止而未完成的 BEGIN … END 事务数据块中，则整个事务（包括 COPY）都将回滚。有关事务的更多信息，请参阅 [BEGIN](r_BEGIN.md)。
# 从 JSON 格式数据执行的 COPY 操作
JSON 数据结构由一组对象 或数组 组成。JSON *对象* 以大括号开头和结尾，并包含名称-值对的无序集合。每个名称和值由冒号分隔，而每个名称/值对由逗号分隔。名称是用双引号括起的字符串。引号字符必须是简单引号 (0x22)，而不能是倾斜引号或“智能”引号。
JSON *数组* 以中括号开头和结尾，并包含由逗号分隔的值的有序集合。值可以是用双引号括起的字符串、数字、布尔值 true 或 false、null、JSON 对象或数组。
JSON 对象和数组可以嵌套，从而实现分层的数据结构。以下示例显示了包含两个有效对象的 JSON 数据结构。
```
{
"id": 1006410,
"title": "Amazon Redshift Database Developer Guide"
}
{
"id": 100540,
"name": "Amazon Simple Storage Service User Guide"
}
```
下面显示了与两个 JSON 数组相同的数据。
```
[
1006410,
"Amazon Redshift Database Developer Guide"
]
[
100540,
"Amazon Simple Storage Service User Guide"
]
```
## JSON 的 COPY 选项
将 COPY 与 JSON 格式数据结合使用时，可以指定以下选项：
+ `'auto' ` – COPY 自动从 JSON 文件加载字段。
+ `'auto ignorecase'` – COPY 自动从 JSON 文件加载字段，同时忽略字段名称的大小写。
+ `s3://jsonpaths_file` – COPY 使用 JSONPaths 文件解析 JSON 源数据。*JSONPaths 文件* 是一个包含单个 JSON 对象的文本文件，其中的对象名称 `"jsonpaths"` 与 JSONPath 表达式数组配对。如果该名称是 `"jsonpaths"` 之外的任何字符串，则 COPY 将使用 `'auto'` 参数而不是使用 JSONPaths 文件。
有关说明如何使用 `'auto'`、`'auto ignorecase'` 或 JSONPaths 文件以及使用 JSON 对象或数组加载数据的示例，请参阅[从 JSON 中复制的示例](r_COPY_command_examples.md#r_COPY_command_examples-copy-from-json)。
## JSONPath 选项
在 Amazon Redshift COPY 语法中，JSONPath 表达式使用括号表示法或点表示法指定 JSON 层次数据结构中单个名称元素的显式路径。Amazon Redshift 不支持可能解析为不确定路径或多个名称元素的任何 JSONPath 元素（如通配符或筛选表达式）。因此，Amazon Redshift 无法解析复杂、多级的数据结构。
下面是包含使用括号表示法的 JSONPath 表达式的 JSONPaths 文件的示例。美元符号 (\$1) 表示根级别结构。
```
{
"jsonpaths": [
"$['id']",
"$['store']['book']['title']",
"$['location'][0]"
]
}
```
在上面的示例中，`$['location'][0]` 引用数组中的第一个元素。JSON 使用从 0 开始的数组索引。数组索引必须是正整数（大于或等于零）。
以下示例显示了使用点表示法的前一个 JSONPaths 文件。
```
{
"jsonpaths": [
"$.id",
"$.store.book.title",
"$.location[0]"
]
}
```
您不能在 `jsonpaths` 数组中将括号表示法和点表示法混合。括号表示法和点表示法中均可使用括号来引用数组元素。
使用点表示法时，JSONPath 表达式不能包含下列字符：
+ 单直引号 ( ' )
+ 句点或点 (.)
+ 中括号 ( [ ] )（除非用于引用数组元素）
如果 JSONPath 表达式引用的名称-值对中的值是对象或数组，则整个对象或数组将作为字符串加载，包括大括号或中括号。例如，假定 JSON 数据包含以下对象。
```
{
"id": 0,
"guid": "84512477-fa49-456b-b407-581d0d851c3c",
"isActive": true,
"tags": [
"nisi",
"culpa",
"ad",
"amet",
"voluptate",
"reprehenderit",
"veniam"
],
"friends": [
{
"id": 0,
"name": "Martha Rivera"
},
{
"id": 1,
"name": "Renaldo"
}
]
}
```
JSONPath 表达式 `$['tags']` 之后将返回以下值。
```
"["nisi","culpa","ad","amet","voluptate","reprehenderit","veniam"]"
```
JSONPath 表达式 `$['friends'][1]` 之后将返回以下值。
```
"{"id": 1,"name": "Renaldo"}"
```
`jsonpaths` 数组中的每个 JSONPath 表达式对应于 Amazon Redshift 目标表中的一个列。`jsonpaths` 数组元素的顺序必须与目标表或列列表（如果使用了列列表）中列的顺序一致。
有关说明如何使用 `'auto'` 参数或 JSONPaths 文件以及使用 JSON 对象或数组加载数据的示例，请参阅[从 JSON 中复制的示例](r_COPY_command_examples.md#r_COPY_command_examples-copy-from-json)。
有关如何复制多个 JSON 文件的信息，请参阅[使用清单指定数据文件](loading-data-files-using-manifest.md)。
## 在 JSON 中转义字符
COPY 会将 `\n` 作为换行符加载并且会将 `\t` 作为制表符加载。要加载反斜杠，请使用反斜杠 ( `\\` ) 对其进行转义。
例如，假设您在桶 `escape.json` 中名为 `s3://amzn-s3-demo-bucket/json/` 的文件中具有以下 JSON。
```
{
"backslash": "This is a backslash: \\",
"newline": "This sentence\n is on two lines.",
"tab": "This sentence \t contains a tab."
}
```
运行下列命令以创建 ESCAPES 表并加载 JSON。
```
create table escapes (backslash varchar(25), newline varchar(35), tab varchar(35));
copy escapes from 's3://amzn-s3-demo-bucket/json/escape.json'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as json 'auto';
```
查询 ESCAPES 表以查看结果。
```
select * from escapes;
backslash | newline | tab
------------------------+-------------------+----------------------------------
This is a backslash: \ | This sentence | This sentence contains a tab.
: is on two lines.
(1 row)
```
## 数值精度丢失
当您将数字从 JSON 格式的数据文件加载到定义为数字数据类型的列时，您可能会丢失精度。某些浮点值在计算机系统中无法准确表示。因此，您从 JSON 文件复制的数据可能无法按预期进行舍入。为避免精度丢失，我们建议使用以下替代方法之一：
+ 通过用双引号字符将值括起来将数字表示为字符串。
+ 使用 [ROUNDEC](copy-parameters-data-conversion.md#copy-roundec) 对数字进行舍入而不是截断。
+ 不要使用 JSON 或 Avro 文件，而应使用 CSV、字符分隔或固定宽度的文本文件。
# 从列式数据格式中执行 COPY 操作
COPY 可采用以下列式格式从 Amazon S3 中加载数据：
+ ORC
+ Parquet
有关从列式数据格式中使用 COPY 的示例，请参阅[COPY 示例](r_COPY_command_examples.md)。
COPY 支持列式数据，但要注意以下几点：
+ Amazon S3 桶必须与 Amazon Redshift 数据库位于同一 AWS 区域。
+ 要通过 VPC 端点访问您的 Amazon S3 数据，请使用 IAM 策略和 IAM 角色设置访问权限，如《Amazon Redshift 管理指南》**中的[将 Amazon Redshift Spectrum 与增强 VPC 路由结合使用](https://docs.aws.amazon.com/redshift/latest/mgmt/spectrum-enhanced-vpc.html)中所述。
+ COPY 不自动应用压缩编码。
+ 仅支持以下 COPY 参数：
+ [ACCEPTINVCHARS](copy-parameters-data-conversion.md#copy-acceptinvchars)（从 ORC 或 Parquet 文件中复制时）。
+ [FILLRECORD](copy-parameters-data-conversion.md#copy-fillrecord)
+ [FROM](copy-parameters-data-source-s3.md#copy-parameters-from)
+ [IAM\$1ROLE](copy-parameters-authorization.md#copy-iam-role)
+ [CREDENTIALS](copy-parameters-authorization.md#copy-credentials)
+ [STATUPDATE ](copy-parameters-data-load.md#copy-statupdate)
+ [MANIFEST](copy-parameters-data-source-s3.md#copy-manifest)
+ [EXPLICIT\$1IDS](copy-parameters-data-conversion.md#copy-explicit-ids)
+ 如果 COPY 在加载时遇到错误，则命令失败。列式数据类型不支持 ACCEPTANYDATE 和 MAXERROR。
+ 错误消息发送至 SQL 客户端。一些错误记录在 STL\$1LOAD\$1ERRORS 和 STL\$1ERROR 中。
+ COPY 会按列在列式数据文件中出现的相同顺序将值插入到目标表的列中。目标表中的列数和数据文件中的列数必须匹配。
+ 如果您为 COPY 操作指定的文件包含下列扩展名之一，我们将解压缩数据，而无需添加任何参数：
+ `.gz`
+ `.snappy`
+ `.bz2`
+ 从 Parquet 和 ORC 文件格式的 COPY 操作使用 Redshift Spectrum 和桶访问。要对这些格式执行 COPY 操作，请确保没有任何阻止使用 Amazon S3 预签名 URL 的 IAM 策略。Amazon Redshift 生成的预签名 URL 有效期为 1 小时，这样 Amazon Redshift 就有足够的时间从 Amazon S3 存储桶中加载所有文件。COPY 操作从列式数据格式中扫描的每个文件都会生成一个唯一的预签名 URL。对于包含 `s3:signatureAge` 操作的存储桶策略，请确保将该值至少设置为 3,600,000 毫秒。有关更多信息，请参阅[将 Amazon Redshift Spectrum 与增强型 VPC 路由结合使用](https://docs.aws.amazon.com/redshift/latest/mgmt/spectrum-enhanced-vpc.html)。
+ 列式数据格式的 COPY 不支持 REGION 参数。即使 Amazon S3 存储桶和数据库位于同一 AWS 区域中，也可能会遇到错误，例如，基于 PARQUET 的 COPY 不支持 Region 参数。
+ 从列格式执行 COPY 操作现在支持并发扩展。要启用并发扩展，请参阅[配置并发扩展队列](https://docs.aws.amazon.com/redshift/latest/dg/concurrency-scaling.html#concurrency-scaling-queues)。
# DATEFORMAT 和 TIMEFORMAT 字符串
COPY 命令使用 DATEFORMAT 和 TIMEFORMAT 选项来解析源数据中的日期和时间值。DATEFORMAT 和 TIMEFORMAT 是格式化字符串，必须与源数据的日期和时间值的格式相匹配。例如，加载具有日期值 `Jan-01-1999` 的源数据的 COPY 命令必须包括以下 DATEFORMAT 字符串：
```
COPY ...
DATEFORMAT AS 'MON-DD-YYYY'
```
有关管理 COPY 数据转换的更多信息，请参阅[数据转换参数](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)。
DATEFORMAT 和 TIMEFORMAT 字符串可包含日期时间分隔符（例如‘`-`’、‘`/`’或‘`:`’）以及下表中的日期部分和时间部分格式。
**注意**
如果您无法将日期或时间值的格式与以下日期部分和时间部分相匹配，或如果您的日期和时间值使用的格式彼此不同，则请将 `'auto'` 参数与 DATEFORMAT 或 TIMEFORMAT 参数结合使用。在使用 DATEFORMAT 或 TIMEFORMAT 字符串时，`'auto'` 参数会识别几种不受支持的格式。有关更多信息，请参阅 [在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别](automatic-recognition.md)。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_DATEFORMAT_and_TIMEFORMAT_strings.html)
默认格式日期是 YYYY-MM-DD。不带时区 (TIMESTAMP) 的默认时间戳格式是 YYYY-MM-DD HH:MI:SS。带时区 (TIMESTAMPTZ) 的默认时间戳格式是 YYYY-MM-DD HH:MI:SSOF，其中 OF 是与 UTC 的偏移两个（例如，-8:00）。您不能在 timeformat\$1string 中包含时区标识符（TZ、tz 或 OF）。秒 (SS) 字段还支持小数秒到微秒级别的细节。要加载格式与默认格式不同的 TIMESTAMPTZ 数据，请指定“自动”。
以下是您在源数据中会遇到的一些示例日期或时间，以及相应的 DATEFORMAT 或 TIMEFORMAT 字符串。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_DATEFORMAT_and_TIMEFORMAT_strings.html)
## 示例
有关使用 TIMEFORMAT 的示例，请参阅[加载时间戳或日期戳](r_COPY_command_examples.md#r_COPY_command_examples-load-a-time-datestamp)。
# 在 DATEFORMAT 和 TIMEFORMAT 中使用自动识别
如果您指定 `'auto'` 作为 DATEFORMAT 或 TIMEFORMAT 参数的参数，Amazon Redshift 将自动识别并转换源数据中的日期格式或时间格式。下面是一个示例。
```
copy favoritemovies from 'dynamodb://ProductCatalog'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
dateformat 'auto';
```
在与 DATEFORMAT 和 TIMEFORMAT 的 `'auto'` 参数一起使用时，COPY 将识别并转换在 [DATEFORMAT 和 TIMEFORMAT 字符串示例](r_DATEFORMAT_and_TIMEFORMAT_strings.md) 中的表中列出的日期和时间格式。此外，`'auto'` 参数将识别下列在使用 DATEFORMAT 和 TIMEFORMAT 字符串时不受支持的格式。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/automatic-recognition.html)
自动识别不支持 epochsec 和 epochmillisec。
要测试是否将自动转换日期或时间戳值，请使用 CAST 函数尝试将字符串转换为日期或时间戳值。例如，下列命令测试时间戳值 `'J2345678 04:05:06.789'`：
```
create table formattest (test char(21));
insert into formattest values('J2345678 04:05:06.789');
select test, cast(test as timestamp) as timestamp, cast(test as date) as date from formattest;
test | timestamp | date
----------------------+---------------------+------------
J2345678 04:05:06.789 1710-02-23 04:05:06 1710-02-23
```
如果 DATE 列的源数据包含时间信息，则将截断时间部分。如果 TIMESTAMP 列的源数据省略时间信息，则将使用 00:00:00 作为时间部分。
# COPY 示例
**注意**
为便于阅读，这些示例包含换行符。请不要在您的 *credentials-args* 字符串中包含换行符或空格。
**Topics**
+ [从 DynamoDB 表中加载 FAVORITEMOVIES](#r_COPY_command_examples-load-favoritemovies-from-an-amazon-dynamodb-table)
+ [从 Amazon S3 桶中加载 LISTING](#r_COPY_command_examples-load-listing-from-an-amazon-s3-bucket)
+ [从 Amazon EMR 集群中加载 LISTING](#copy-command-examples-emr)
+ [Example: COPY from Amazon S3 using a manifest](#copy-command-examples-manifest)
+ [从以竖线（默认分隔符）分隔的文件中加载 LISTING](#r_COPY_command_examples-load-listing-from-a-pipe-delimited-file-default-delimiter)
+ [使用 Parquet 格式的列式数据加载 LISTING](#r_COPY_command_examples-load-listing-from-parquet)
+ [使用 ORC 格式的列式数据加载 LISTING](#r_COPY_command_examples-load-listing-from-orc)
+ [使用选项加载 EVENT](#r_COPY_command_examples-load-event-with-options)
+ [从固定宽度的数据文件中加载 VENUE](#r_COPY_command_examples-load-venue-from-a-fixed-width-data-file)
+ [从 CSV 文件中加载 CATEGORY](#load-from-csv)
+ [加载具有显式的 IDENTITY 列值的 VENUE](#r_COPY_command_examples-load-venue-with-explicit-values-for-an-identity-column)
+ [从以竖线分隔的 GZIP 文件中加载 TIME](#r_COPY_command_examples-load-time-from-a-pipe-delimited-gzip-file)
+ [加载时间戳或日期戳](#r_COPY_command_examples-load-a-time-datestamp)
+ [从具有默认值的文件中加载数据](#r_COPY_command_examples-load-data-from-a-file-with-default-values)
+ [使用 ESCAPE 选项复制数据](#r_COPY_command_examples-copy-data-with-the-escape-option)
+ [从 JSON 中复制的示例](#r_COPY_command_examples-copy-from-json)
+ [从 Avro 中复制的示例](#r_COPY_command_examples-copy-from-avro)
+ [使用 ESCAPE 选项为 COPY 准备文件](#r_COPY_preparing_data)
+ [将 shapefile 加载到 Amazon Redshift](#copy-example-spatial-copy-shapefile)
+ [带有 NOLOAD 选项的 COPY 命令](#r_COPY_command_examples-load-noload-option)
+ [带有多字节分隔符和 ENCODING 选项的 COPY 命令](#r_COPY_command_examples-load-encoding-multibyte-delimiter-option)
## 从 DynamoDB 表中加载 FAVORITEMOVIES
AWS 开发工具包包括一个创建名为 *Movies* 的 DynamoDB 表的简单示例。（有关此示例，请参阅 [DynamoDB 入门](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.html)。） 以下示例加载包含 DynamoDB 表中数据的 Amazon Redshift MOVIES 表。Amazon Redshift 表必须已存在于数据库中。
```
copy favoritemovies from 'dynamodb://Movies'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
readratio 50;
```
## 从 Amazon S3 桶中加载 LISTING
以下示例从 Amazon S3 桶加载 LISTING。COPY 命令将加载 `/data/listing/` 文件夹中的所有文件。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listing/'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
## 从 Amazon EMR 集群中加载 LISTING
以下示例从 Amazon EMR 集群的 lzop 压缩文件加载使用制表符分隔数据的 SALES 表。COPY 加载 `myoutput/` 文件夹中每个以 `part-` 开头的文件。
```
copy sales
from 'emr://j-SAMPLE2B500FC/myoutput/part-*'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '\t' lzop;
```
以下示例将加载包含 Amazon EMR 集群中的 JSON 格式的数据的 SALES 表。COPY 加载 `myoutput/json/` 文件夹中的每个文件。
```
copy sales
from 'emr://j-SAMPLE2B500FC/myoutput/json/'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
JSON 's3://amzn-s3-demo-bucket/jsonpaths.txt';
```
## 使用清单指定数据文件
您可以使用清单确保 COPY 命令将从 Amazon S3 加载所有必需的文件，而且仅加载必需的文件。当您需要从不同的桶加载多个文件或加载未共享相同前缀的文件时，您也可使用清单。
例如，假设您需要加载下列三个文件：`custdata1.txt`、`custdata2.txt` 和 `custdata3.txt`。您可使用以下命令通过指定前缀来加载 `amzn-s3-demo-bucket` 中以 `custdata` 开头的所有文件：
```
copy category
from 's3://amzn-s3-demo-bucket/custdata'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
如果由于错误仅存在两个文件，则 COPY 仅加载这两个文件并成功完成，从而导致不完整的数据加载。如果桶还包含恰巧使用相同前缀的不需要的文件（例如名为 `custdata.backup` 的文件），则 COPY 还加载此文件，从而导致加载不需要的数据。
为了确保加载所有必需的文件并防止加载不需要的文件，您可使用清单文件。清单是 JSON 格式的文本文件，其中列出了要通过 COPY 命令处理的文件。例如，以下清单将加载上例中的三个文件。
```
{
"entries":[
{
"url":"s3://amzn-s3-demo-bucket/custdata.1",
"mandatory":true
},
{
"url":"s3://amzn-s3-demo-bucket/custdata.2",
"mandatory":true
},
{
"url":"s3://amzn-s3-demo-bucket/custdata.3",
"mandatory":true
}
]
}
```
可选的 `mandatory` 标志指示 COPY 是否应在文件不存在时终止。默认为 `false`。如果未找到任何文件，则无论 mandatory 设置如何，COPY 都会终止。在此示例中，如果未找到任何文件，COPY 将返回错误。将忽略可能会在仅指定键前缀（如 `custdata.backup`）的情况下选取的不需要的文件，因为它们不在清单上。
在从采用 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
}
}
]
}
```
以下示例使用名为 `cust.manifest` 的清单。
```
copy customer
from 's3://amzn-s3-demo-bucket/cust.manifest'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as orc
manifest;
```
您可以使用清单来加载不同桶或文件中未共享相同前缀的文件。以下示例显示了用于加载名称以日期戳开头的文件中的数据的 JSON。
```
{
"entries": [
{"url":"s3://amzn-s3-demo-bucket/2013-10-04-custdata.txt","mandatory":true},
{"url":"s3://amzn-s3-demo-bucket/2013-10-05-custdata.txt","mandatory":true},
{"url":"s3://amzn-s3-demo-bucket/2013-10-06-custdata.txt","mandatory":true},
{"url":"s3://amzn-s3-demo-bucket/2013-10-07-custdata.txt","mandatory":true}
]
}
```
此清单可列出位于不同桶中的文件，前提是桶与集群位于同一 AWS 区域。
```
{
"entries": [
{"url":"s3://amzn-s3-demo-bucket1/custdata1.txt","mandatory":false},
{"url":"s3://amzn-s3-demo-bucket2/custdata1.txt","mandatory":false},
{"url":"s3://amzn-s3-demo-bucket2/custdata2.txt","mandatory":false}
]
}
```
## 从以竖线（默认分隔符）分隔的文件中加载 LISTING
以下示例是一个非常简单的示例，其中未指定任何选项并且输入文件包含默认分隔符，即竖线字符（“\$1”）。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listings_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole';
```
## 使用 Parquet 格式的列式数据加载 LISTING
以下示例从 Amazon S3 上的名为 parquet 的文件夹加载数据。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listings/parquet/'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as parquet;
```
## 使用 ORC 格式的列式数据加载 LISTING
以下示例从 Amazon S3 上名为 `orc` 的文件夹加载数据。
```
copy listing
from 's3://amzn-s3-demo-bucket/data/listings/orc/'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as orc;
```
## 使用选项加载 EVENT
以下示例将竖线分隔的数据加载到 EVENT 表中并应用下列规则：
+ 如果使用了引号对来括起任何字符串，则会删除它们。
+ 空字符串和包含空白的字符串将作为 NULL 值加载。
+ 如果返回了 5 个以上的错误，则加载失败。
+ 时间戳值必须遵循指定的格式；例如，有效的时间戳为 `2008-09-26 05:43:12`。
```
copy event
from 's3://amzn-s3-demo-bucket/data/allevents_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
removequotes
emptyasnull
blanksasnull
maxerror 5
delimiter '|'
timeformat 'YYYY-MM-DD HH:MI:SS';
```
## 从固定宽度的数据文件中加载 VENUE
```
copy venue
from 's3://amzn-s3-demo-bucket/data/venue_fw.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
fixedwidth 'venueid:3,venuename:25,venuecity:12,venuestate:2,venueseats:6';
```
上例假设数据文件与所示的样本数据是使用相同的方式设置格式的。在下面的示例中，空格充当占位符，以便所有列的宽度与规范中的规定相同：
```
1 Toyota Park Bridgeview IL0
2 Columbus Crew Stadium Columbus OH0
3 RFK Stadium Washington DC0
4 CommunityAmerica BallparkKansas City KS0
5 Gillette Stadium Foxborough MA68756
```
## 从 CSV 文件中加载 CATEGORY
假设您要加载具有下表中所示值的 CATEGORY。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_COPY_command_examples.html)
以下示例显示了字段值用逗号隔开的文本文件的内容。
```
12,Shows,Musicals,Musical theatre
13,Shows,Plays,All "non-musical" theatre
14,Shows,Opera,All opera, light, and "rock" opera
15,Concerts,Classical,All symphony, concerto, and choir concerts
```
如果您在加载文件时使用 DELIMITER 参数指定逗号分隔的输入，则 COPY 命令失败，因为一些输入字段包含逗号。您可通过使用 CSV 参数并将包含逗号的字段括在引号字符中来避免以上问题。如果用引号括起来的字符串中出现引号字符，则需要通过双引号字符来进行转义。默认引号字符为双引号，因此您需要使用一个额外的双引号对每个双引号进行转义。您的新输入文件与下面类似。
```
12,Shows,Musicals,Musical theatre
13,Shows,Plays,"All ""non-musical"" theatre"
14,Shows,Opera,"All opera, light, and ""rock"" opera"
15,Concerts,Classical,"All symphony, concerto, and choir concerts"
```
假定文件名为 `category_csv.txt`，则可通过使用以下 COPY 命令加载文件：
```
copy category
from 's3://amzn-s3-demo-bucket/data/category_csv.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
csv;
```
或者，若要避免对输入中的双引号进行转义，可通过使用 QUOTE AS 参数来指定其他引号字符。例如，以下版本的 `category_csv.txt` 使用“`%`”作为引号字符。
```
12,Shows,Musicals,Musical theatre
13,Shows,Plays,%All "non-musical" theatre%
14,Shows,Opera,%All opera, light, and "rock" opera%
15,Concerts,Classical,%All symphony, concerto, and choir concerts%
```
以下 COPY 命令使用 QUOTE AS 来加载 `category_csv.txt`：
```
copy category
from 's3://amzn-s3-demo-bucket/data/category_csv.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
csv quote as '%';
```
## 加载具有显式的 IDENTITY 列值的 VENUE
以下示例假设在创建 VENUE 表时，至少将一个列（如 `venueid` 列）指定为 IDENTITY 列。此命令将覆盖 IDENTITY 列的自动生成值的默认 IDENTITY 行为，并将改为从 venue.txt 文件加载显式值。使用 EXLICIT\$1IDS 选项时，Amazon Redshift 不会检查表中是否加载了重复的 IDENTITY 值。
```
copy venue
from 's3://amzn-s3-demo-bucket/data/venue.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
explicit_ids;
```
## 从以竖线分隔的 GZIP 文件中加载 TIME
以下示例从用竖线分隔的 GZIP 文件加载 TIME 表：
```
copy time
from 's3://amzn-s3-demo-bucket/data/timerows.gz'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
gzip
delimiter '|';
```
## 加载时间戳或日期戳
以下示例加载具有带格式的时间戳的数据。
**注意**
`HH:MI:SS` 的 TIMEFORMAT 还可支持超出 `SS` 的高达微秒细节级别的小数秒。此示例中使用的文件 `time.txt` 包含一行，即 `2009-01-12 14:15:57.119568`。
```
copy timestamp1
from 's3://amzn-s3-demo-bucket/data/time.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
timeformat 'YYYY-MM-DD HH:MI:SS';
```
此复制的结果如下所示：
```
select * from timestamp1;
c1
----------------------------
2009-01-12 14:15:57.119568
(1 row)
```
## 从具有默认值的文件中加载数据
以下示例使用 TICKIT 数据库中的 VENUE 表的变体。考虑使用以下语句定义的 VENUE\$1NEW 表：
```
create table venue_new(
venueid smallint not null,
venuename varchar(100) not null,
venuecity varchar(30),
venuestate char(2),
venueseats integer not null default '1000');
```
考虑未包含任何 VENUESEATS 列值的 venue\$1noseats.txt 数据文件，如以下示例中所示：
```
1|Toyota Park|Bridgeview|IL|
2|Columbus Crew Stadium|Columbus|OH|
3|RFK Stadium|Washington|DC|
4|CommunityAmerica Ballpark|Kansas City|KS|
5|Gillette Stadium|Foxborough|MA|
6|New York Giants Stadium|East Rutherford|NJ|
7|BMO Field|Toronto|ON|
8|The Home Depot Center|Carson|CA|
9|Dick's Sporting Goods Park|Commerce City|CO|
10|Pizza Hut Park|Frisco|TX|
```
以下 COPY 语句将成功地从此文件中加载表并对已省略的列应用 DEFAULT 值（“1000”）：
```
copy venue_new(venueid, venuename, venuecity, venuestate)
from 's3://amzn-s3-demo-bucket/data/venue_noseats.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|';
```
现在查看加载的表：
```
select * from venue_new order by venueid;
venueid | venuename | venuecity | venuestate | venueseats
---------+----------------------------+-----------------+------------+------------
1 | Toyota Park | Bridgeview | IL | 1000
2 | Columbus Crew Stadium | Columbus | OH | 1000
3 | RFK Stadium | Washington | DC | 1000
4 | CommunityAmerica Ballpark | Kansas City | KS | 1000
5 | Gillette Stadium | Foxborough | MA | 1000
6 | New York Giants Stadium | East Rutherford | NJ | 1000
7 | BMO Field | Toronto | ON | 1000
8 | The Home Depot Center | Carson | CA | 1000
9 | Dick's Sporting Goods Park | Commerce City | CO | 1000
10 | Pizza Hut Park | Frisco | TX | 1000
(10 rows)
```
在以下示例中，除了假设此文件中未包含任何 VENUESEATS 数据之外，还假设未包含任何 VENUENAME 数据：
```
1||Bridgeview|IL|
2||Columbus|OH|
3||Washington|DC|
4||Kansas City|KS|
5||Foxborough|MA|
6||East Rutherford|NJ|
7||Toronto|ON|
8||Carson|CA|
9||Commerce City|CO|
10||Frisco|TX|
```
通过使用相同的表定义，以下 COPY 语句失败，因为未为 VENUENAME 指定任何 DEFAULT 值，并且 VENUENAME 是一个非 NULL 列：
```
copy venue(venueid, venuecity, venuestate)
from 's3://amzn-s3-demo-bucket/data/venue_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|';
```
现在考虑使用 IDENTITY 列的 VENUE 表的变体：
```
create table venue_identity(
venueid int identity(1,1),
venuename varchar(100) not null,
venuecity varchar(30),
venuestate char(2),
venueseats integer not null default '1000');
```
与上例一样，假设 VENUESEATS 列没有源文件中的对应值。以下 COPY 语句成功地加载表（包括预先定义的 IDENTITY 数据值）而不是自动生成这些值：
```
copy venue(venueid, venuename, venuecity, venuestate)
from 's3://amzn-s3-demo-bucket/data/venue_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|' explicit_ids;
```
此语句将失败，因为它未包含 IDENTITY 列（列列表中缺少 VENUEID），而是包含 EXPLICIT\$1IDS 参数：
```
copy venue(venuename, venuecity, venuestate)
from 's3://amzn-s3-demo-bucket/data/venue_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|' explicit_ids;
```
此语句将失败，因为它不包含 EXPLICIT\$1IDS 参数：
```
copy venue(venueid, venuename, venuecity, venuestate)
from 's3://amzn-s3-demo-bucket/data/venue_pipe.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|';
```
## 使用 ESCAPE 选项复制数据
以下示例演示如何加载与分隔符字符（在此示例中为竖线字符）匹配的字符。在输入文件中，确保使用反斜杠字符 (\$1) 转义您要加载的所有竖线字符 (\$1)。然后使用 ESCAPE 参数加载此文件。
```
$ more redshiftinfo.txt
1|public\|event\|dwuser
2|public\|sales\|dwuser
create table redshiftinfo(infoid int,tableinfo varchar(50));
copy redshiftinfo from 's3://amzn-s3-demo-bucket/data/redshiftinfo.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
delimiter '|' escape;
select * from redshiftinfo order by 1;
infoid | tableinfo
-------+--------------------
1 | public|event|dwuser
2 | public|sales|dwuser
(2 rows)
```
如果没有 ESCAPE 参数，此 COPY 命令将失败，并返回 `Extra column(s) found` 错误。
**重要**
如果使用包含 ESCAPE 参数的 COPY 加载数据，则还必须在 UNLOAD 命令中指定 ESCAPE 参数与以生成反向输出文件。同样，如果您使用 ESCAPE 参数执行 UNLOAD 命令，则在您对相同数据执行 COPY 操作时需要使用 ESCAPE 参数。
## 从 JSON 中复制的示例
在以下示例中，您加载具有以下数据的 CATEGORY 表。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_COPY_command_examples.html)
**Topics**
+ [使用“auto”选项从 JSON 数据中加载](#copy-from-json-examples-using-auto)
+ [使用“auto ignorecase”选项从 JSON 数据中加载](#copy-from-json-examples-using-auto-ignorecase)
+ [使用 JSONPaths 文件从 JSON 数据中加载](#copy-from-json-examples-using-jsonpaths)
+ [使用 JSONPaths 文件从 JSON 数组中加载](#copy-from-json-examples-using-jsonpaths-arrays)
### 使用“auto”选项从 JSON 数据中加载
要使用 `'auto'` 选项从 JSON 数据加载，JSON 数据必须包含一组对象。键名称必须与列名称匹配，但顺序并不重要。下面显示了名为 `category_object_auto.json` 的文件的内容。
```
{
"catdesc": "Major League Baseball",
"catid": 1,
"catgroup": "Sports",
"catname": "MLB"
}
{
"catgroup": "Sports",
"catid": 2,
"catname": "NHL",
"catdesc": "National Hockey League"
}
{
"catid": 3,
"catname": "NFL",
"catgroup": "Sports",
"catdesc": "National Football League"
}
{
"bogus": "Bogus Sports LLC",
"catid": 4,
"catgroup": "Sports",
"catname": "NBA",
"catdesc": "National Basketball Association"
}
{
"catid": 5,
"catgroup": "Shows",
"catname": "Musicals",
"catdesc": "All symphony, concerto, and choir concerts"
}
```
若要从上例中的 JSON 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_object_auto.json'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
json 'auto';
```
### 使用“auto ignorecase”选项从 JSON 数据中加载
要使用 `'auto ignorecase'` 选项从 JSON 数据加载，JSON 数据必须包含一组对象。键名称的大小写不必与列名称匹配，顺序并不重要。下面显示了名为 `category_object_auto-ignorecase.json` 的文件的内容。
```
{
"CatDesc": "Major League Baseball",
"CatID": 1,
"CatGroup": "Sports",
"CatName": "MLB"
}
{
"CatGroup": "Sports",
"CatID": 2,
"CatName": "NHL",
"CatDesc": "National Hockey League"
}
{
"CatID": 3,
"CatName": "NFL",
"CatGroup": "Sports",
"CatDesc": "National Football League"
}
{
"bogus": "Bogus Sports LLC",
"CatID": 4,
"CatGroup": "Sports",
"CatName": "NBA",
"CatDesc": "National Basketball Association"
}
{
"CatID": 5,
"CatGroup": "Shows",
"CatName": "Musicals",
"CatDesc": "All symphony, concerto, and choir concerts"
}
```
若要从上例中的 JSON 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_object_auto ignorecase.json'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
json 'auto ignorecase';
```
### 使用 JSONPaths 文件从 JSON 数据中加载
如果 JSON 数据对象未直接对应于列名称，则可使用 JSONPaths 文件将 JSON 元素映射到列。顺序在 JSON 源数据中也不重要，但 JSONPaths 文件表达式的顺序必须与列顺序匹配。假设您具有以下名为 `category_object_paths.json` 的数据文件。
```
{
"one": 1,
"two": "Sports",
"three": "MLB",
"four": "Major League Baseball"
}
{
"three": "NHL",
"four": "National Hockey League",
"one": 2,
"two": "Sports"
}
{
"two": "Sports",
"three": "NFL",
"one": 3,
"four": "National Football League"
}
{
"one": 4,
"two": "Sports",
"three": "NBA",
"four": "National Basketball Association"
}
{
"one": 6,
"two": "Shows",
"three": "Musicals",
"four": "All symphony, concerto, and choir concerts"
}
```
以下名为 `category_jsonpath.json` 的 JSONPaths 文件会将源数据映射到表列。
```
{
"jsonpaths": [
"$['one']",
"$['two']",
"$['three']",
"$['four']"
]
}
```
若要从上例中的 JSON 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_object_paths.json'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
json 's3://amzn-s3-demo-bucket/category_jsonpath.json';
```
### 使用 JSONPaths 文件从 JSON 数组中加载
若要从包含一组数组的 JSON 数据加载，必须使用 JSONPaths 文件将数组元素映射到列。假设您具有以下名为 `category_array_data.json` 的数据文件。
```
[1,"Sports","MLB","Major League Baseball"]
[2,"Sports","NHL","National Hockey League"]
[3,"Sports","NFL","National Football League"]
[4,"Sports","NBA","National Basketball Association"]
[5,"Concerts","Classical","All symphony, concerto, and choir concerts"]
```
以下名为 `category_array_jsonpath.json` 的 JSONPaths 文件会将源数据映射到表列。
```
{
"jsonpaths": [
"$[0]",
"$[1]",
"$[2]",
"$[3]"
]
}
```
若要从上例中的 JSON 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_array_data.json'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
json 's3://amzn-s3-demo-bucket/category_array_jsonpath.json';
```
## 从 Avro 中复制的示例
在以下示例中，您加载具有以下数据的 CATEGORY 表。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_COPY_command_examples.html)
**Topics**
+ [使用“auto”选项从 Avro 数据中加载](#copy-from-avro-examples-using-auto)
+ [使用“auto ignorecase”选项从 Avro 数据中加载](#copy-from-avro-examples-using-auto-ignorecase)
+ [使用 JSONPaths 文件从 Avro 数据中加载](#copy-from-avro-examples-using-avropaths)
### 使用“auto”选项从 Avro 数据中加载
若要使用 `'auto'` 参数从 Avro 数据加载，Avro schema 中的字段名称必须与列名称匹配。在使用 `'auto'` 参数时，顺序并不重要。下面显示了名为 `category_auto.avro` 的文件的 schema。
```
{
"name": "category",
"type": "record",
"fields": [
{"name": "catid", "type": "int"},
{"name": "catdesc", "type": "string"},
{"name": "catname", "type": "string"},
{"name": "catgroup", "type": "string"},
}
```
Avro 文件中的数据为二进制格式，不是人类可读的格式。下面显示了 `category_auto.avro` 文件中的数据的 JSON 表示形式。
```
{
"catid": 1,
"catdesc": "Major League Baseball",
"catname": "MLB",
"catgroup": "Sports"
}
{
"catid": 2,
"catdesc": "National Hockey League",
"catname": "NHL",
"catgroup": "Sports"
}
{
"catid": 3,
"catdesc": "National Basketball Association",
"catname": "NBA",
"catgroup": "Sports"
}
{
"catid": 4,
"catdesc": "All symphony, concerto, and choir concerts",
"catname": "Classical",
"catgroup": "Concerts"
}
```
要从上例中的 Avro 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_auto.avro'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as avro 'auto';
```
### 使用“auto ignorecase”选项从 Avro 数据中加载
若要使用 `'auto ignorecase'` 参数从 Avro 数据加载，Avro schema 中的字段名称的大小写不必与列名称的大小写匹配。在使用 `'auto ignorecase'` 参数时，顺序并不重要。下面显示了名为 `category_auto-ignorecase.avro` 的文件的 schema。
```
{
"name": "category",
"type": "record",
"fields": [
{"name": "CatID", "type": "int"},
{"name": "CatDesc", "type": "string"},
{"name": "CatName", "type": "string"},
{"name": "CatGroup", "type": "string"},
}
```
Avro 文件中的数据为二进制格式，不是人类可读的格式。下面显示了 `category_auto-ignorecase.avro` 文件中的数据的 JSON 表示形式。
```
{
"CatID": 1,
"CatDesc": "Major League Baseball",
"CatName": "MLB",
"CatGroup": "Sports"
}
{
"CatID": 2,
"CatDesc": "National Hockey League",
"CatName": "NHL",
"CatGroup": "Sports"
}
{
"CatID": 3,
"CatDesc": "National Basketball Association",
"CatName": "NBA",
"CatGroup": "Sports"
}
{
"CatID": 4,
"CatDesc": "All symphony, concerto, and choir concerts",
"CatName": "Classical",
"CatGroup": "Concerts"
}
```
要从上例中的 Avro 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_auto-ignorecase.avro'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format as avro 'auto ignorecase';
```
### 使用 JSONPaths 文件从 Avro 数据中加载
如果 Avro schema 中的字段名称未直接对应于列名称，则可使用 JSONPaths 文件将 schema 元素映射到列。JSONPaths 文件表达式的顺序必须与列顺序一致。
假设您具有名为 `category_paths.avro` 的数据文件，其中包含的数据与上例相同，但具有以下架构。
```
{
"name": "category",
"type": "record",
"fields": [
{"name": "id", "type": "int"},
{"name": "desc", "type": "string"},
{"name": "name", "type": "string"},
{"name": "group", "type": "string"},
{"name": "region", "type": "string"}
]
}
```
以下名为 `category_path.avropath` 的 JSONPaths 文件会将源数据映射到表列。
```
{
"jsonpaths": [
"$['id']",
"$['group']",
"$['name']",
"$['desc']"
]
}
```
要从上例中的 Avro 数据文件加载，请执行以下 COPY 命令。
```
copy category
from 's3://amzn-s3-demo-bucket/category_object_paths.avro'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
format avro 's3://amzn-s3-demo-bucket/category_path.avropath ';
```
## 使用 ESCAPE 选项为 COPY 准备文件
以下示例描述了在使用包含 ESCAPE 参数的 COPY 命令将数据导入到 Amazon Redshift 表中之前，如何准备数据以“转义”换行符。如果未准备数据以限定换行符，则 Amazon Redshift 将会在您运行 COPY 命令时返回加载错误，因为换行符一般用作记录分隔符。
例如，考虑要复制到 Amazon Redshift 表中的一个文件或外部表中的一个列。如果该文件或列包含 XML 格式的内容或类似数据，则需要确保使用反斜杠字符 (\$1) 转义此内容中的所有换行符 (\$1n)。
包含嵌入换行符的文件或表提供了相对轻松的匹配模式。每个嵌入的换行符很有可能始终跟随一个 `>` 字符（在这二者之间可能还包含一些空格字符（`' '` 或制表符）），如下面的名为 `nlTest1.txt` 的文本文件的示例中所示。
```
$ cat nlTest1.txt
|1000
|2000
```
在以下示例中，您可运行文本处理实用工具预先处理源文件，并在需要的位置插入转义字符。（`|` 字符旨在用作分隔符，以便在列数据复制到 Amazon Redshift 表中后分隔这些数据。）
```
$ sed -e ':a;N;$!ba;s/>[[:space:]]*\n/>\\\n/g' nlTest1.txt > nlTest2.txt
```
同样，可使用 Perl 执行类似操作：
```
cat nlTest1.txt | perl -p -e 's/>\s*\n/>\\\n/g' > nlTest2.txt
```
为了便于将 `nlTest2.txt` 文件中的数据加载到 Amazon Redshift 中，我们在 Amazon Redshift 中创建了一个包含两列的表。第一列 c1 是字符列，用于放置 `nlTest2.txt` 文件中 XML 格式的内容。第二列 c2 将放置从同一文件加载的整数值。
在运行 `sed` 命令后，可使用 ESCAPE 参数将 `nlTest2.txt` 文件中的数据正确地加载到 Amazon Redshift 表中。
**注意**
如果您在 COPY 命令中包含 ESCAPE 参数，则它会将一些包含反斜杠字符的特殊字符（包括换行符）进行转义。
```
copy t2 from 's3://amzn-s3-demo-bucket/data/nlTest2.txt'
iam_role 'arn:aws:iam::0123456789012:role/MyRedshiftRole'
escape
delimiter as '|';
select * from t2 order by 2;
c1 | c2
-------------+------
| 1000
| 2000
(2 rows)
```
您可以类似方式准备从外部数据库导出的数据文件。例如，对于 Oracle 数据库，可对要复制到 Amazon Redshift 中的表中的每个受影响的列使用 REPLACE 函数。
```
SELECT c1, REPLACE(c2, \n',\\n' ) as c2 from my_table_with_xml
```
此外，许多用于定期处理大量数据的数据库导出和提取、转换、加载 (ETL) 工具提供了指定转义字符和分隔符字符的选项。
## 将 shapefile 加载到 Amazon Redshift
以下示例演示如何使用 COPY 加载 Esri shapefile。有关加载 shapefile 的更多信息，请参阅[将 shapefile 加载到 Amazon Redshift](spatial-copy-shapefile.md)。
### 加载一个 shapefile
以下步骤介绍如何使用 COPY 命令从 Amazon S3 中摄取 OpenStreetMap 数据。此示例假定 [Geofabrik 下载站点的](https://download.geofabrik.de/europe.html) Norway shapefile 归档已经上载到 AWS 区域中的私有 Amazon S3 桶。`.shp`、`.shx` 和 `.dbf` 文件必须共享相同的 Amazon S3 前缀和文件名。
#### 无需简化即可摄取数据
以下命令可创建表并摄取可适合最大几何大小的数据，而无需进行任何简化。在您的首选 GIS 软件中打开 `gis_osm_natural_free_1.shp`，然后检查此图层中的列。预设情况下，IDENTITY 或 GEOMETRY 列位于首位。当 GEOMETRY 列位于首位时，您可以创建表，如下所示。
```
CREATE TABLE norway_natural (
wkb_geometry GEOMETRY,
osm_id BIGINT,
code INT,
fclass VARCHAR,
name VARCHAR);
```
或者，当 IDENTITY 列位于首位时，您可以创建表，如下所示。
```
CREATE TABLE norway_natural_with_id (
fid INT IDENTITY(1,1),
wkb_geometry GEOMETRY,
osm_id BIGINT,
code INT,
fclass VARCHAR,
name VARCHAR);
```
现在，您可以使用 COPY 摄取数据。
```
COPY norway_natural FROM 's3://bucket_name/shapefiles/norway/gis_osm_natural_free_1.shp'
FORMAT SHAPEFILE
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_natural' completed, 83891 record(s) loaded successfully
```
或者，您可以按如下所示摄取数据。
```
COPY norway_natural_with_id FROM 's3://bucket_name/shapefiles/norway/gis_osm_natural_free_1.shp'
FORMAT SHAPEFILE
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_natural_with_id' completed, 83891 record(s) loaded successfully.
```
#### 通过简化摄取数据
以下命令创建一个表，并尝试在不进行任何简化的情况下摄取无法适合最大几何大小的数据。检查 `gis_osm_water_a_free_1.shp` shapefile 并创建相应的表，如下所示。
```
CREATE TABLE norway_water (
wkb_geometry GEOMETRY,
osm_id BIGINT,
code INT,
fclass VARCHAR,
name VARCHAR);
```
当 COPY 命令运行时，会导致错误。
```
COPY norway_water FROM 's3://bucket_name/shapefiles/norway/gis_osm_water_a_free_1.shp'
FORMAT SHAPEFILE
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
ERROR: Load into table 'norway_water' failed. Check 'stl_load_errors' system table for details.
```
查询 `STL_LOAD_ERRORS` 显示几何体过大。
```
SELECT line_number, btrim(colname), btrim(err_reason) FROM stl_load_errors WHERE query = pg_last_copy_id();
line_number | btrim | btrim
-------------+--------------+-----------------------------------------------------------------------
1184705 | wkb_geometry | Geometry size: 1513736 is larger than maximum supported size: 1048447
```
为了克服这个问题，将 `SIMPLIFY AUTO` 参数添加到 COPY 命令中以简化几何体。
```
COPY norway_water FROM 's3://bucket_name/shapefiles/norway/gis_osm_water_a_free_1.shp'
FORMAT SHAPEFILE
SIMPLIFY AUTO
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_water' completed, 1989196 record(s) loaded successfully.
```
要查看简化的行和几何体，请查询 `SVL_SPATIAL_SIMPLIFY`。
```
SELECT * FROM svl_spatial_simplify WHERE query = pg_last_copy_id();
query | line_number | maximum_tolerance | initial_size | simplified | final_size | final_tolerance
-------+-------------+-------------------+--------------+------------+------------+----------------------
20 | 1184704 | -1 | 1513736 | t | 1008808 | 1.276386653895e-05
20 | 1664115 | -1 | 1233456 | t | 1023584 | 6.11707814796635e-06
```
使用容差低于自动计算容差的 SIMPLIFY AUTO *max\$1tolerance* 可能会导致摄入误差。在这种情况下，请使用 MAXERROR 忽略错误。
```
COPY norway_water FROM 's3://bucket_name/shapefiles/norway/gis_osm_water_a_free_1.shp'
FORMAT SHAPEFILE
SIMPLIFY AUTO 1.1E-05
MAXERROR 2
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_water' completed, 1989195 record(s) loaded successfully.
INFO: Load into table 'norway_water' completed, 1 record(s) could not be loaded. Check 'stl_load_errors' system table for details.
```
再次查询 `SVL_SPATIAL_SIMPLIFY` 来识别 COPY 未成功加载的记录。
```
SELECT * FROM svl_spatial_simplify WHERE query = pg_last_copy_id();
query | line_number | maximum_tolerance | initial_size | simplified | final_size | final_tolerance
-------+-------------+-------------------+--------------+------------+------------+-----------------
29 | 1184704 | 1.1e-05 | 1513736 | f | 0 | 0
29 | 1664115 | 1.1e-05 | 1233456 | t | 794432 | 1.1e-05
```
在这个示例中，第一条记录没有成功适应，因此 `simplified` 列显示为 false。第二条记录已在给定容差范围内加载。但是，最终大小比使用自动计算的容差大，而不指定最大公差。
### 正在从压缩的 shapefile 文件加载
Amazon Redshift COPY 支持从压缩的 shapefile 中摄取数据。所有 shapefile 组件必须具有相同的 Amazon S3 前缀和相同的压缩后缀。例如，假设您要加载上面示例中的数据。在本例中，文件 `gis_osm_water_a_free_1.shp.gz`、`gis_osm_water_a_free_1.dbf.gz` 和 `gis_osm_water_a_free_1.shx.gz` 必须共享相同的 Amazon S3 目录。COPY 命令需要 GZIP 选项，FROM 子句必须指定正确的压缩文件，如下所示。
```
COPY norway_natural FROM 's3://bucket_name/shapefiles/norway/compressed/gis_osm_natural_free_1.shp.gz'
FORMAT SHAPEFILE
GZIP
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_natural' completed, 83891 record(s) loaded successfully.
```
### 正在将数据加载到具有不同列顺序的表
如果您有一个没有将 `GEOMETRY` 作为第一列的表，则可以使用列映射将列映射到目标表。例如，创建一个将 `osm_id` 指定为第一列的表。
```
CREATE TABLE norway_natural_order (
osm_id BIGINT,
wkb_geometry GEOMETRY,
code INT,
fclass VARCHAR,
name VARCHAR);
```
然后使用列映射摄取 shapefile。
```
COPY norway_natural_order(wkb_geometry, osm_id, code, fclass, name)
FROM 's3://bucket_name/shapefiles/norway/gis_osm_natural_free_1.shp'
FORMAT SHAPEFILE
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/MyRoleName';
INFO: Load into table 'norway_natural_order' completed, 83891 record(s) loaded successfully.
```
### 将数据加载到具有 geography 列的表中
如果某个表具有 `GEOGRAPHY` 列，请首先提取到 `GEOMETRY` 列，然后将对象强制转换为 `GEOGRAPHY` 对象。例如，在将 shapefile 复制到 `GEOMETRY` 列后，对表进行更改，添加 `GEOGRAPHY` 数据类型。
```
ALTER TABLE norway_natural ADD COLUMN wkb_geography GEOGRAPHY;
```
然后将 geometry 转换为 geography。
```
UPDATE norway_natural SET wkb_geography = wkb_geometry::geography;
```
（可选）您可以删除 `GEOMETRY` 列。
```
ALTER TABLE norway_natural DROP COLUMN wkb_geometry;
```
## 带有 NOLOAD 选项的 COPY 命令
要在实际加载数据之前验证数据文件，请使用带有 NOLOAD 选项的 COPY 命令。Amazon Redshift 会解析输入文件并显示发生的任何错误。以下示例使用 NOLOAD 选项，实际上并未将任何行加载到表中。
```
COPY public.zipcode1
FROM 's3://amzn-s3-demo-bucket/mydata/zipcode.csv'
DELIMITER ';'
IGNOREHEADER 1 REGION 'us-east-1'
NOLOAD
CREDENTIALS 'aws_iam_role=arn:aws:iam::123456789012:role/myRedshiftRole';
Warnings:
Load into table 'zipcode1' completed, 0 record(s) loaded successfully.
```
## 带有多字节分隔符和 ENCODING 选项的 COPY 命令
以下示例从包含多字节数据的 Amazon S3 文件中加载 LATIN1。COPY 命令以八进制形式 `\302\246\303\254` 指定分隔符，来分隔编码为 ISO-8859-1 的输入文件中的字段。要以 UTF-8 形式指定相同的分隔符，请指定 `DELIMITER '¦ì'`。
```
COPY latin1
FROM 's3://amzn-s3-demo-bucket/multibyte/myfile'
IAM_ROLE 'arn:aws:iam::123456789012:role/myRedshiftRole'
DELIMITER '\302\246\303\254'
ENCODING ISO88591
```