从补丁 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 参数参考 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)