从补丁 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/)。
# SQL 命令
SQL 语言包括各种命令，您可以使用这些命令来创建和处理数据库对象、运行查询、加载表和修改表中的数据。
Amazon Redshift 基于 PostgreSQL。Amazon Redshift 和 PostgreSQL 之间的差别非常大，您在设计和开发数据仓库应用程序时必须注意这一点。有关 Amazon Redshift SQL 与 PostgreSQL 之间的差异的更多信息，请参阅[Amazon Redshift 和 PostgreSQL](c_redshift-and-postgres-sql.md)。
**注意**
单个 SQL 语句的最大大小为 16MB。
**Topics**
+ [ABORT](r_ABORT.md)
+ [ALTER DATABASE](r_ALTER_DATABASE.md)
+ [ALTER DATASHARE](r_ALTER_DATASHARE.md)
+ [ALTER DEFAULT PRIVILEGES](r_ALTER_DEFAULT_PRIVILEGES.md)
+ [ALTER EXTERNAL SCHEMA](r_ALTER_EXTERNAL_SCHEMA.md)
+ [ALTER EXTERNAL VIEW](r_ALTER_EXTERNAL_VIEW.md)
+ [ALTER FUNCTION](r_ALTER_FUNCTION.md)
+ [ALTER GROUP](r_ALTER_GROUP.md)
+ [ALTER IDENTITY PROVIDER](r_ALTER_IDENTITY_PROVIDER.md)
+ [ALTER MASKING POLICY](r_ALTER_MASKING_POLICY.md)
+ [ALTER MATERIALIZED VIEW](r_ALTER_MATERIALIZED_VIEW.md)
+ [ALTER RLS POLICY](r_ALTER_RLS_POLICY.md)
+ [ALTER ROLE](r_ALTER_ROLE.md)
+ [ALTER PROCEDURE](r_ALTER_PROCEDURE.md)
+ [ALTER SCHEMA](r_ALTER_SCHEMA.md)
+ [ALTER SYSTEM](r_ALTER_SYSTEM.md)
+ [ALTER TABLE](r_ALTER_TABLE.md)
+ [ALTER TABLE APPEND](r_ALTER_TABLE_APPEND.md)
+ [ALTER TEMPLATE](r_ALTER_TEMPLATE.md)
+ [ALTER USER](r_ALTER_USER.md)
+ [ANALYZE](r_ANALYZE.md)
+ [ANALYZE COMPRESSION](r_ANALYZE_COMPRESSION.md)
+ [ATTACH MASKING POLICY](r_ATTACH_MASKING_POLICY.md)
+ [ATTACH RLS POLICY](r_ATTACH_RLS_POLICY.md)
+ [BEGIN](r_BEGIN.md)
+ [CALL](r_CALL_procedure.md)
+ [CANCEL](r_CANCEL.md)
+ [CLOSE](close.md)
+ [COMMENT](r_COMMENT.md)
+ [COMMIT](r_COMMIT.md)
+ [COPY](r_COPY.md)
+ [CREATE DATABASE](r_CREATE_DATABASE.md)
+ [CREATE DATASHARE](r_CREATE_DATASHARE.md)
+ [CREATE EXTERNAL FUNCTION](r_CREATE_EXTERNAL_FUNCTION.md)
+ [CREATE EXTERNAL MODEL](r_create_external_model.md)
+ [CREATE EXTERNAL SCHEMA](r_CREATE_EXTERNAL_SCHEMA.md)
+ [CREATE EXTERNAL TABLE](r_CREATE_EXTERNAL_TABLE.md)
+ [CREATE EXTERNAL VIEW](r_CREATE_EXTERNAL_VIEW.md)
+ [CREATE FUNCTION](r_CREATE_FUNCTION.md)
+ [CREATE GROUP](r_CREATE_GROUP.md)
+ [CREATE IDENTITY PROVIDER](r_CREATE_IDENTITY_PROVIDER.md)
+ [CREATE LIBRARY](r_CREATE_LIBRARY.md)
+ [CREATE MASKING POLICY](r_CREATE_MASKING_POLICY.md)
+ [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)
+ [CREATE MODEL](r_CREATE_MODEL.md)
+ [CREATE PROCEDURE](r_CREATE_PROCEDURE.md)
+ [CREATE RLS POLICY](r_CREATE_RLS_POLICY.md)
+ [CREATE ROLE](r_CREATE_ROLE.md)
+ [CREATE SCHEMA](r_CREATE_SCHEMA.md)
+ [CREATE TABLE](r_CREATE_TABLE_NEW.md)
+ [CREATE TABLE AS](r_CREATE_TABLE_AS.md)
+ [CREATE TEMPLATE](r_CREATE_TEMPLATE.md)
+ [CREATE USER](r_CREATE_USER.md)
+ [CREATE VIEW](r_CREATE_VIEW.md)
+ [DEALLOCATE](r_DEALLOCATE.md)
+ [DECLARE](declare.md)
+ [DELETE](r_DELETE.md)
+ [DESC DATASHARE](r_DESC_DATASHARE.md)
+ [DESC IDENTITY PROVIDER](r_DESC_IDENTITY_PROVIDER.md)
+ [DETACH MASKING POLICY](r_DETACH_MASKING_POLICY.md)
+ [DETACH RLS POLICY](r_DETACH_RLS_POLICY.md)
+ [DROP DATABASE](r_DROP_DATABASE.md)
+ [DROP DATASHARE](r_DROP_DATASHARE.md)
+ [DROP EXTERNAL VIEW](r_DROP_EXTERNAL_VIEW.md)
+ [DROP FUNCTION](r_DROP_FUNCTION.md)
+ [DROP GROUP](r_DROP_GROUP.md)
+ [DROP IDENTITY PROVIDER](r_DROP_IDENTITY_PROVIDER.md)
+ [DROP LIBRARY](r_DROP_LIBRARY.md)
+ [DROP MASKING POLICY](r_DROP_MASKING_POLICY.md)
+ [DROP MODEL](r_DROP_MODEL.md)
+ [DROP MATERIALIZED VIEW](materialized-view-drop-sql-command.md)
+ [DROP PROCEDURE](r_DROP_PROCEDURE.md)
+ [DROP RLS POLICY](r_DROP_RLS_POLICY.md)
+ [DROP ROLE](r_DROP_ROLE.md)
+ [DROP SCHEMA](r_DROP_SCHEMA.md)
+ [DROP TABLE](r_DROP_TABLE.md)
+ [DROP TEMPLATE](r_DROP_TEMPLATE.md)
+ [DROP USER](r_DROP_USER.md)
+ [DROP VIEW](r_DROP_VIEW.md)
+ [END](r_END.md)
+ [EXECUTE](r_EXECUTE.md)
+ [EXPLAIN](r_EXPLAIN.md)
+ [FETCH](fetch.md)
+ [GRANT](r_GRANT.md)
+ [INSERT](r_INSERT_30.md)
+ [INSERT（外部表）](r_INSERT_external_table.md)
+ [LOCK](r_LOCK.md)
+ [MERGE](r_MERGE.md)
+ [PREPARE](r_PREPARE.md)
+ [REFRESH MATERIALIZED VIEW](materialized-view-refresh-sql-command.md)
+ [RESET](r_RESET.md)
+ [REVOKE](r_REVOKE.md)
+ [ROLLBACK](r_ROLLBACK.md)
+ [SELECT](r_SELECT_synopsis.md)
+ [SELECT INTO](r_SELECT_INTO.md)
+ [SET](r_SET.md)
+ [SET SESSION AUTHORIZATION](r_SET_SESSION_AUTHORIZATION.md)
+ [SET SESSION CHARACTERISTICS](r_SET_SESSION_CHARACTERISTICS.md)
+ [SHOW](r_SHOW.md)
+ [SHOW COLUMN GRANTS](r_SHOW_COLUMN_GRANTS.md)
+ [SHOW COLUMNS](r_SHOW_COLUMNS.md)
+ [SHOW CONSTRAINTS](r_SHOW_CONSTRAINTS.md)
+ [SHOW EXTERNAL TABLE](r_SHOW_EXTERNAL_TABLE.md)
+ [SHOW DATABASES](r_SHOW_DATABASES.md)
+ [SHOW FUNCTIONS](r_SHOW_FUNCTIONS.md)
+ [SHOW GRANTS](r_SHOW_GRANTS.md)
+ [SHOW MODEL](r_SHOW_MODEL.md)
+ [SHOW DATASHARES](r_SHOW_DATASHARES.md)
+ [SHOW PARAMETERS](r_SHOW_PARAMETERS.md)
+ [SHOW POLICIES](r_SHOW_POLICIES.md)
+ [SHOW PROCEDURE](r_SHOW_PROCEDURE.md)
+ [SHOW PROCEDURES](r_SHOW_PROCEDURES.md)
+ [SHOW SCHEMAS](r_SHOW_SCHEMAS.md)
+ [SHOW TABLE](r_SHOW_TABLE.md)
+ [SHOW TABLES](r_SHOW_TABLES.md)
+ [SHOW TEMPLATE](r_SHOW_TEMPLATE.md)
+ [SHOW TEMPLATES](r_SHOW_TEMPLATES.md)
+ [SHOW VIEW](r_SHOW_VIEW.md)
+ [START TRANSACTION](r_START_TRANSACTION.md)
+ [TRUNCATE](r_TRUNCATE.md)
+ [UNLOAD](r_UNLOAD.md)
+ [UPDATE](r_UPDATE.md)
+ [USE](r_USE_command.md)
+ [VACUUM](r_VACUUM_command.md)
# ABORT
停止当前正在运行的事务，并放弃该事务执行的所有更新。ABORT 对已完成的事务没有任何效果。
此命令执行与 ROLLBACK 命令相同的功能。有关信息，请参阅 [ROLLBACK](r_ROLLBACK.md)。
## 语法
```
ABORT [ WORK | TRANSACTION ]
```
## 参数
WORK
可选关键字。
TRANSACTION
可选关键字；WORK 和 TRANSACTION 同义。
## 示例
以下示例创建一个表，然后启动将数据插入到表的事务。然后，ABORT 命令将回滚数据插入操作，以便将表保持为空表。
以下命令创建一个名为 MOVIE\$1GROSS 的示例表：
```
create table movie_gross( name varchar(30), gross bigint );
```
下一组命令启动将两个数据行插入到表中的事务：
```
begin;
insert into movie_gross values ( 'Raiders of the Lost Ark', 23400000);
insert into movie_gross values ( 'Star Wars', 10000000 );
```
接下来，以下命令从表中选择数据，表明已插入成功：
```
select * from movie_gross;
```
命令输出表明已成功插入两行：
```
name | gross
------------------------+----------
Raiders of the Lost Ark | 23400000
Star Wars | 10000000
(2 rows)
```
现在，此命令将数据更改回滚到事务开始的位置：
```
abort;
```
现在，从表中选择数据时，显示这是一个空表：
```
select * from movie_gross;
name | gross
------+-------
(0 rows)
```
# ALTER DATABASE
更改数据库的属性。
## 所需的权限
要使用 ALTER DATABASE，需要以下权限之一。
+ Superuser
+ 具有 ALTER DATABASE 权限的用户
+ 数据库拥有者
## 语法
```
ALTER DATABASE database_name
{
RENAME TO new_name
| OWNER TO new_owner
| [ CONNECTION LIMIT { limit | UNLIMITED } ]
[ COLLATE { CASE_SENSITIVE | CS | CASE_INSENSITIVE | CI } ]
[ ISOLATION LEVEL { SNAPSHOT | SERIALIZABLE } ]
| INTEGRATION
{
REFRESH { { ALL | INERROR } TABLES [ IN SCHEMA schema [, ...] ] | TABLE schema.table [, ...] }
| SET
[ QUERY_ALL_STATES [=] { TRUE | FALSE } ]
[ ACCEPTINVCHARS [=] { TRUE | FALSE } ]
[ REFRESH_INTERVAL ]
[ TRUNCATECOLUMNS [=] { TRUE | FALSE } ]
[ HISTORY_MODE [=] {TRUE | FALSE} [ FOR { {ALL} TABLES [IN SCHEMA schema [, ...] ] | TABLE schema.table [, ...] } ] ]
}
}
```
## 参数
*database\$1name*
要更改的数据库的名称。通常，您将更改当前未连接到的数据库；在任何情况下，更改只在后续的会话中才会生效。您可以更改当前数据库的所有者，但不能重命名该数据库：
```
alter database tickit rename to newtickit;
ERROR: current database may not be renamed
```
RENAME TO
重命名指定的数据库。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。不能重命名 dev、padb\$1harvest、template0、template1 或 sys:internal 数据库，也不能重命名当前数据库。只有数据库所有者或 [superuser](r_superusers.md#def_superusers) 可以重命名数据库；非超级用户所有者还必须具有 CREATEDB 权限。
*new\$1name*
新数据库名称。
OWNER TO
更改指定数据库的所有者。您可以更改当前数据库或其他某个数据库的所有者。只有超级用户可以更改所有者。
*new\$1owner*
新数据库所有者。新所有者必须是具有写入权限的现有数据库用户。有关用户权限的更多信息，请参阅[GRANT](r_GRANT.md)。
CONNECTION LIMIT \$1 *limit* \$1 UNLIMITED \$1
允许用户同时打开的数据库连接的最大数量。此限制不适用于超级用户。使用 UNLIMITED 关键字设置允许的并行连接的最大数量。可能对每个用户的连接数量也会施加限制。有关更多信息，请参阅 [CREATE USER](r_CREATE_USER.md)。默认为 UNLIMITED。要查看当前连接，请查询 [STV\$1SESSIONS](r_STV_SESSIONS.md) 系统视图。
如果用户及数据库连接限制均适用，当用户尝试连接时，必须有一个同时低于这两个限制的未使用的连接槽可用。
COLLATE \$1 CASE\$1SENSITIVE \$1 CS \$1 CASE\$1INSENSITIVE \$1 CI \$1
指定字符串搜索或比较是区分大小写还是不区分大小写的子句。
您可以更改当前数据库的区分大小写，即使数据库为空也是如此。
您必须对当前数据库具有 ALTER 权限，才能更改区分大小写设置。具有 CREATE DATABASE 权限的超级用户或数据库拥有者也可以更改数据库的区分大小写设置。
CASE\$1SENSITIVE 和 CS 可以互换，生成的结果相同。同样，CASE\$1INSENSITIVE 和 CI 可以互换，生成的结果相同。
ISOLATION LEVEL \$1 SNAPSHOT \$1 SERIALIZABLE \$1
指定针对数据库运行查询时使用的隔离级别的子句。有关隔离级别的更多信息，请参阅[Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
+ SNAPSHOT 隔离 – 提供隔离级别，来防止出现更新和删除冲突。
+ SERIALIZABLE 隔离–为并发事务提供完全可序列性。
更改数据库的隔离级别时，请考虑以下项目：
+ 您必须对当前数据库具有超级用户或 CREATE DATABASE 权限，才能更改数据库隔离级别。
+ 您不能更改 `dev` 数据库的隔离级别。
+ 您不能更改事务块中的隔离级别。
+ 如果有其他用户连接到数据库，则更改隔离级别命令将失败。
+ 更改隔离级别命令可以更改当前会话的隔离级别设置。
INTEGRATION
更改零 ETL 集成数据库。
REFRESH \$1\$1 ALL \$1 INERROR \$1 TABLES [IN SCHEMA *schema* [, ...]] \$1 TABLE *schema.table* [, ...]\$1
指定 Amazon Redshift 是否刷新指定架构或表中的所有表或有错误的表的子句。刷新将触发从源数据库完全复制指定架构或表中的表。
有关更多信息，请参阅《Amazon Redshift 管理指南》**中的[零 ETL 集成](https://docs.aws.amazon.com/redshift/latest/mgmt/zero-etl-using.html)。有关集成状态的更多信息，请参阅[SVV\$1INTEGRATION\$1TABLE\$1STATE](r_SVV_INTEGRATION_TABLE_STATE.md)和[SVV\$1INTEGRATION](r_SVV_INTEGRATION.md)。
QUERY\$1ALL\$1STATES [=] \$1 TRUE \$1 FALSE \$1
QUERY\$1ALL\$1STATES 子句设置是否可以在所有状态（`Synced`、`Failed`、`ResyncRequired` 和 `ResyncInitiated`）下查询零 ETL 集成表。默认情况下，只能在 `Synced` 状态下查询零 ETL 集成表。
ACCEPTINVCHARS [=] \$1 TRUE \$1 FALSE \$1
ACCEPTINVCHARS 子句设置在检测到 VARCHAR 数据类型的无效字符时，零 ETL 集成表是否继续摄取。在遇到无效字符时，无效字符将被替换为默认 `?` 字符。
REFRESH\$1INTERVAL
REFRESH\$1INTERVAL 子句设置将数据从零 ETL 源刷新到目标数据库的大致时间间隔（秒）。对于源类型为 Aurora MySQL、Aurora PostgreSQL 或 RDS for MySQL 的零 ETL 集成，`interval` 可设置为 0-432000 秒（5 天）。对于 Amazon DynamoDB 零 ETL 集成，`interval` 可设置为 900-432000 秒（15 分钟 - 5 天）。
有关使用零 ETL 集成创建数据库的更多信息，请参阅*《Amazon Redshift 管理指南》*中的[在 Amazon Redshift 中创建目标数据库](https://docs.aws.amazon.com/redshift/latest/mgmt/zero-etl-using.creating-db.html)。
TRUNCATECOLUMNS [=] \$1 TRUE \$1 FALSE \$1
TRUNCATECOLUMNS 子句设置当 VARCHAR 列或 SUPER 列属性的值超出限制时，零 ETL 集成表是否继续摄取。当为 `TRUE` 时，值会被截断以适合该列，而溢出的 JSON 属性的值会被截断以适合 SUPER 列。
HISTORY\$1MODE [=] \$1TRUE \$1 FALSE\$1 [ FOR \$1 \$1ALL\$1 TABLES [IN SCHEMA schema [, ...]] \$1 TABLE schema.table [, ...]\$1 ]
一个子句，用于指定 Amazon Redshift 是否为所有表或指定架构中参与零 ETL 集成的表设置历史记录模式。此选项仅适用于为零 ETL 集成创建的数据库。
HISTORY\$1MODE 子句可设置为 `TRUE` 或 `FALSE`。默认值为 `FALSE`。启用和禁用历史记录模式仅适用于处于 `Synced` 状态的表。有关 HISTORY\$1MODE 的信息，请参阅《Amazon Redshift 管理指南》**中的[历史记录模式](https://docs.aws.amazon.com/redshift/latest/mgmt/zero-etl-history-mode.html)。
## 使用说明
ALTER DATABASE 命令应用于后续会话，而不应用于当前会话。您必须重新连接到更改后的数据库，以查看更改结果。
## 示例
以下示例将一个名为 TICKIT\$1SANDBOX 的数据库重命名为 TICKIT\$1TEST：
```
alter database tickit_sandbox rename to tickit_test;
```
以下示例将 TICKIT 数据库（当前数据库）的所有者更改为 DWUSER：
```
alter database tickit owner to dwuser;
```
以下示例更改了 sampledb 数据库的数据库区分大小写：
```
ALTER DATABASE sampledb COLLATE CASE_INSENSITIVE;
```
以下示例使用 SNAPSHOT 隔离级别更改名为 **sampledb** 的数据库。
```
ALTER DATABASE sampledb ISOLATION LEVEL SNAPSHOT;
```
以下示例刷新零 ETL 集成的数据库 **sample\$1integration\$1db** 中的表 **schema1.sample\$1table1** 和 **schema2.sample\$1table2**。
```
ALTER DATABASE sample_integration_db INTEGRATION REFRESH TABLE schema1.sample_table1, schema2.sample_table2;
```
以下示例刷新零 ETL 集成中所有已同步和失败的表。
```
ALTER DATABASE sample_integration_db INTEGRATION REFRESH ALL tables;
```
下面的示例将零 ETL 集成的刷新间隔设置为 600 秒。
```
ALTER DATABASE sample_integration_db INTEGRATION SET REFRESH_INTERVAL 600;
```
下面的示例刷新架构 **sample\$1schema** 中处于 `ErrorState` 的所有表。
```
ALTER DATABASE sample_integration_db INTEGRATION REFRESH INERROR TABLES in SCHEMA sample_schema;
```
以下示例为表 `myschema.table1` 启用历史记录模式。
```
ALTER DATABASE sample_integration_db INTEGRATION SET HISTORY_MODE = true FOR TABLE myschema.table1
```
以下示例为 `myschema` 中的所有表启用历史记录模式。
```
ALTER DATABASE sample_integration_db INTEGRATION SET HISTORY_MODE = true for ALL TABLES IN SCHEMA myschema
```
# ALTER DATASHARE
更改数据共享的定义。您可以使用 ALTER DATASHARE 添加对象或删除对象。您只能更改当前数据库中的数据共享。将对象从关联数据库添加到数据共享中或者从数据共享中删除对象。对要添加或删除的数据共享具有所需权限的数据共享拥有者可以更改数据共享。
## 所需的权限
以下是 ALTER DATASHARE 所需的权限：
+ 超级用户。
+ 具有 ALTER DATASHARE 权限的用户。
+ 对数据共享具有 ALTER 或 ALL 权限的用户。
+ 要将特定对象添加到数据共享中，用户必须具有对象的权限。在此例中，用户应是对象的拥有者，或者具有这些对象的 SELECT、USAGE 或 ALL 权限。
## 语法
以下语法展示了如何向数据共享添加或删除对象。
```
ALTER DATASHARE datashare_name { ADD | REMOVE } {
TABLE schema.table [, ...]
| SCHEMA schema [, ...]
| FUNCTION schema.sql_udf (argtype,...) [, ...]
| ALL TABLES IN SCHEMA schema [, ...]
| ALL FUNCTIONS IN SCHEMA schema [, ...] }
```
以下语法展示了如何配置数据共享的属性。
```
ALTER DATASHARE datashare_name {
[ SET PUBLICACCESSIBLE [=] TRUE | FALSE ]
[ SET INCLUDENEW [=] TRUE | FALSE FOR SCHEMA schema ] }
```
## 参数
*datashare\$1name*
要更改的数据共享的名称。
ADD \$1 REMOVE
指定是向数据集中添加对象还是从中删除对象的子句。
TABLE *schema*.*table* [, ...]
要添加到数据共享的指定 schema 中的表或视图的名称。
SCHEMA *schema* [, ...]
要添加到数据共享中的 schema 的名称。
FUNCTION *schema*.*sql\$1udf* (argtype,...) [, ...]
要添加到数据共享的用户定义的 SQL 函数的名称和参数类型。
ALL TABLES IN SCHEMA *schema* [, ...]
指定是否将指定 schema 中的所有表和视图添加到数据共享中的子句。
ALL FUNCTIONS IN SCHEMA *schema* [, ...] \$1
指定将指定 schema 中的所有函数添加到数据共享中的子句。
[ SET PUBLICACCESSIBLE [=] TRUE \$1 FALSE ]
指定是否可以将数据共享共享给可公开访问的集群的子句。
[ SET INCLUDENEW [=] TRUE \$1 FALSE FOR SCHEMA *schema* ]
指定是否将在指定 schema 中创建的任何未来表、视图或 SQL 用户定义函数 (UDF) 添加到数据共享中的子句。指定 schema 中的当前表、视图或 SQL UDF 不会添加到数据共享中。只有超级用户才可以更改每个数据共享-schema 对的此属性。预设情况下，INCLUDENEW 子句为 false。
## ALTER DATASHARE 使用说明
+ 以下用户可以更改数据共享：
+ 超级用户
+ 数据共享的拥有者
+ 对数据共享具有 ALTER 或 ALL 权限的用户
+ 要将特定对象添加到数据共享中，用户必须具有对象的正确权限。用户应该是对象的拥有者，或者对这些对象具有 SELECT、USAGE 或 ALL 权限。
+ 您可以共享 schema、表、常规视图、后期绑定视图、实体化视图和 SQL 用户定义函数 (UDF)。在架构中添加对象之前，首先将架构添加到数据共享中。
当您添加 schema 时，Amazon Redshift 不会在其下添加所有对象。您必须显式添加它们。
+ 我们建议您在可公开访问的设置处于开启状态下创建 AWS Data Exchange 数据共享。
+ 通常，我们不建议您使用 ALTER DATASHARE 语句更改 AWS Data Exchange 数据共享，以关闭公开可访问性。如果您这样做的话，如果其集群可以公开访问，有权访问数据共享的 AWS 账户 将失去访问权限。执行这种类型的更改可能会违反 AWS Data Exchange 中的数据产品条款。对于此建议的例外情况，请参阅以下内容。
以下示例显示了设置处于关闭状态下创建 AWS Data Exchange 数据共享时发生的错误。
```
ALTER DATASHARE salesshare SET PUBLICACCESSIBLE FALSE;
ERROR: Alter of ADX-managed datashare salesshare requires session variable datashare_break_glass_session_var to be set to value 'c670ba4db22f4b'
```
要允许更改 AWS Data Exchange 数据共享，以禁用可公开访问的设置，请设置以下变量，然后再次运行 ALTER DATASHARE 语句。
```
SET datashare_break_glass_session_var to 'c670ba4db22f4b';
```
```
ALTER DATASHARE salesshare SET PUBLICACCESSIBLE FALSE;
```
在这种情况下，Amazon Redshift 会生成一个随机的一次性值来设置会话变量，以允许对 AWS Data Exchange 数据共享执行 ALTER DATASHARE SET PUBLICACCESSIBLE FALSE。
## 示例
以下示例将 `public` 架构添加到数据共享 `salesshare` 中。
```
ALTER DATASHARE salesshare ADD SCHEMA public;
```
以下示例将 `public.tickit_sales_redshift` 表添加到了数据共享 `salesshare` 中。
```
ALTER DATASHARE salesshare ADD TABLE public.tickit_sales_redshift;
```
以下示例将所有表添加到了数据共享 `salesshare` 中。
```
ALTER DATASHARE salesshare ADD ALL TABLES IN SCHEMA PUBLIC;
```
以下示例删除了数据共享 `salesshare` 中的 `public.tickit_sales_redshift` 表。
```
ALTER DATASHARE salesshare REMOVE TABLE public.tickit_sales_redshift;
```
# ALTER DEFAULT PRIVILEGES
定义默认访问权限集，这些权限将应用于指定的用户在以后创建的对象。默认情况下，用户只能更改他们自己的默认访问权限。只有超级用户能够为其他用户指定默认权限。
您可以将默认权限应用到角色、用户或用户组。您可以为在当前数据库中创建的所有对象全局设置默认权限，也可以仅为在指定的架构中创建的对象进行此设置。
默认权限仅应用于新对象。运行 ALTER DEFAULT PRIVILEGES 时不会更改现有对象的权限。要授予对数据库或架构中任何用户创建的所有当前和将来对象的权限，请参阅[限定范围权限](https://docs.aws.amazon.com/redshift/latest/dg/t_scoped-permissions.html)。
要查看有关数据库用户的默认权限的信息，请查询 [PG\$1DEFAULT\$1ACL](r_PG_DEFAULT_ACL.md) 系统目录表。
有关权限的更多信息，请参阅 [GRANT](r_GRANT.md)。
## 所需的权限
以下是 ALTER DEFAULT PRIVILEGES 所需的权限：
+ Superuser
+ 具有 ALTER DEFAULT PRIVILEGES 权限的用户
+ 更改自己的默认访问权限的用户
+ 为其具有访问权限的 Schema 设置权限的用户
## 语法
```
ALTER DEFAULT PRIVILEGES
[ FOR USER target_user [, ...] ]
[ IN SCHEMA schema_name [, ...] ]
grant_or_revoke_clause
where grant_or_revoke_clause is one of:
GRANT { { SELECT | INSERT | UPDATE | DELETE | DROP | REFERENCES | TRUNCATE } [,...] | ALL [ PRIVILEGES ] }
ON TABLES
TO { user_name [ WITH GRANT OPTION ] | ROLE role_name | GROUP group_name | PUBLIC } [, ...]
GRANT { EXECUTE | ALL [ PRIVILEGES ] }
ON FUNCTIONS
TO { user_name [ WITH GRANT OPTION ] | ROLE role_name | GROUP group_name | PUBLIC } [, ...]
GRANT { EXECUTE | ALL [ PRIVILEGES ] }
ON PROCEDURES
TO { user_name [ WITH GRANT OPTION ] | ROLE role_name | GROUP group_name | PUBLIC } [, ...]
REVOKE [ GRANT OPTION FOR ] { { SELECT | INSERT | UPDATE | DELETE | REFERENCES | TRUNCATE } [,...] | ALL [ PRIVILEGES ] }
ON TABLES
FROM user_name [, ...] [ RESTRICT ]
REVOKE { { SELECT | INSERT | UPDATE | DELETE | REFERENCES | TRUNCATE } [,...] | ALL [ PRIVILEGES ] }
ON TABLES
FROM { ROLE role_name | GROUP group_name | PUBLIC } [, ...] [ RESTRICT ]
REVOKE [ GRANT OPTION FOR ] { EXECUTE | ALL [ PRIVILEGES ] }
ON FUNCTIONS
FROM user_name [, ...] [ RESTRICT ]
REVOKE { EXECUTE | ALL [ PRIVILEGES ] }
ON FUNCTIONS
FROM { ROLE role_name | GROUP group_name | PUBLIC } [, ...] [ RESTRICT ]
REVOKE [ GRANT OPTION FOR ] { EXECUTE | ALL [ PRIVILEGES ] }
ON PROCEDURES
FROM user_name [, ...] [ RESTRICT ]
REVOKE { EXECUTE | ALL [ PRIVILEGES ] }
ON PROCEDURES
FROM { ROLE role_name | GROUP group_name | PUBLIC } [, ...] [ RESTRICT ]
```
## 参数
FOR USER *target\$1user*
可选。为其定义默认权限的用户的名称。只有超级用户能够为其他用户指定默认权限。默认值为当前用户。
IN SCHEMA *schema\$1name*
可选。如果出现 IN SCHEMA 子句，则指定默认权限将应用于在指定 *schema\$1name* 中创建的新对象。在这种情况下，作为 ALTER DEFAULT PRIVILEGES 目标的用户或用户组必须对指定 schema 拥有 CREATE 权限。特定于某个 schema 的默认权限将添加到现有的全局默认权限中。默认情况下，默认权限全局应用于整个数据库。
GRANT
针对指定用户创建的所有新表和视图、函数或存储过程，向指定的用户或组授予的权限集。与使用 [GRANT](r_GRANT.md) 命令一样，您可以使用 GRANT 子句来设置相同的权限和选项。
WITH GRANT OPTION
一个子句，指示接收权限的用户又可以将相同权限授予其他用户。您无法将 WITH GRANT OPTION 授予组或 PUBLIC。
TO *user\$1name* \$1 ROLE *role\$1name* \$1 GROUP *group\$1name*
将指定的默认权限应用于的用户、角色或用户组的名称。
REVOKE
针对指定用户创建的所有新表、函数或存储过程，从指定的用户或组撤销权限集。与使用 [REVOKE](r_REVOKE.md) 命令一样，您可以使用 REVOKE 子句来设置相同的权限和选项。
GRANT OPTION FOR
一个子句，仅撤消将指定的权限授予其他用户的选项，而不撤消权限本身。您无法从组或 PUBLIC 撤消 GRANT OPTION。
FROM *user\$1name* \$1 ROLE *role\$1name* \$1 GROUP *group\$1name*
默认情况下从其撤消指定权限的用户、角色或用户组的名称。
RESTRICT
RESTRICT 选项仅会撤消用户直接授予的权限。这是默认值。
## 示例
假设您希望允许用户组 `report_readers` 中的所有用户查看用户 `report_admin` 创建的所有表和视图。在这种情况下，以超级用户身份执行以下命令。
```
alter default privileges for user report_admin grant select on tables to group report_readers;
```
在以下示例中，第一个命令授予对您创建的所有新表的 SELECT 权限。无论何时创建新视图，都必须显式授予对该视图的权限，或者再次运行 `alter default privileges` 命令。
```
alter default privileges grant select on tables to public;
```
以下示例针对您在 `sales_admin` schema 中创建的所有新表和视图，将 INSERT 权限授予 `sales` 用户组。
```
alter default privileges in schema sales grant insert on tables to group sales_admin;
```
以下示例撤消上述示例中 ALTER DEFAULT PRIVILEGES 命令的执行效果。
```
alter default privileges in schema sales revoke insert on tables from group sales_admin;
```
默认情况下，PUBLIC 用户组对所有新的用户定义的函数具有执行权限。要撤消对您的新函数的 `public` 执行权限，然后只将执行权限授予 `dev_test` 用户组，请运行以下命令。
```
alter default privileges revoke execute on functions from public;
alter default privileges grant execute on functions to group dev_test;
```
# ALTER EXTERNAL SCHEMA
更改当前数据库中的现有外部架构。只有架构拥有者、超级用户或对架构具有 ALTER 权限的用户才能更改架构。只能更改从 DATA CATALOG、KAFKA 或 MSK 创建的外部架构。
此 schema 的所有者为 CREATE EXTERNAL SCHEMA 命令的发布者。要移交外部 schema 的所有权，请使用 ALTER SCHEMA 更改所有者。要为其他用户或用户组授予对架构的访问权限，请使用 GRANT 命令。
您无法针对外部表的权限使用 GRANT 或 REVOKE 命令。相反，您可以授予或撤销对外部 schema 的权限。
有关更多信息，请参阅下列内容：
+ [ALTER SCHEMA](r_ALTER_SCHEMA.md)
+ [GRANT](r_GRANT.md)
+ [REVOKE](r_REVOKE.md)
+ [CREATE EXTERNAL SCHEMA](r_CREATE_EXTERNAL_SCHEMA.md)
+ [为现有外部架构启用 mTLS 身份验证](materialized-view-streaming-ingestion-mtls.md#materialized-view-streaming-ingestion-mtls-alter)
要查看外部架构的详细信息，请查询 SVV\$1EXTERNAL\$1SCHEMAS 系统视图。有关更多信息，请参阅 [SVV\$1EXTERNAL\$1SCHEMAS](r_SVV_EXTERNAL_SCHEMAS.md)。
## 语法
```
ALTER EXTERNAL SCHEMA schema_name
[ IAM_ROLE [ default | 'SESSION' | 'arn:aws:iam:::role/' ] ]
[ AUTHENTICATION [ none | iam | mtls] ]
[ AUTHENTICATION_ARN 'acm-certificate-arn' | SECRET_ARN 'asm-secret-arn' ]
[ URI 'Kafka bootstrap URL' ]
```
如果您有一个用于流式摄取的现有外部架构，并且想要实现双向 TLS 进行身份验证，则可以运行如下命令，该命令在 ACM 中指定 mTLS 身份验证和 ACM 证书 ARN。
```
ALTER EXTERNAL SCHEMA schema_name
AUTHENTICATION mtls
AUTHENTICATION_ARN 'arn:aws:acm:us-east-1:444455556666:certificate/certificate_ID';
```
或者，您可以参考 Secrets Manager 中的密钥 ARN 来修改 mTLS 身份验证。
```
ALTER EXTERNAL SCHEMA schema_name
AUTHENTICATION mtls
SECRET_ARN 'arn:aws:secretsmanager:us-east-1:012345678910:secret:myMTLSSecret';
```
以下示例显示了如何修改 ALTER EXTERNAL SCHEMA 的 URI：
```
ALTER EXTERNAL SCHEMA schema_name
URI 'lkc-ghidef-67890.centralus.azure.glb.confluent.cloud:9092';
```
以下示例显示了如何修改 ALTER EXTERNAL SCHEMA 的 IAM 角色：
```
ALTER EXTERNAL SCHEMA schema_name
IAM_ROLE 'arn:aws:iam::012345678901:role/testrole';
```
## 参数
IAM\$1ROLE[ default \$1 'SESSION' \$1 'arn:aws:iam:::role/' ]
使用 `default` 关键字让 Amazon Redshift 使用设置为默认值的 IAM 角色。
如果您使用联合身份连接到 Amazon Redshift 集群并访问使用此命令创建的外部架构中的表，则使用 `'SESSION'`。
有关更多信息，请参阅 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。
AUTHENTICATION
为流式摄取定义的身份验证类型。具有身份验证类型的流式摄取使用 Apache Kafka、Confluent Cloud 和 Amazon Managed Streaming for Apache Kafka。有关更多信息，请参阅 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。
AUTHENTICATION\$1ARN
Amazon Redshift 用于通过 Apache Kafka、Confluent Cloud 或 Amazon Managed Streaming for Apache Kafka（Amazon MSK）进行 mtls 身份验证的 AWS Certificate Manager 证书的 ARN。当您选择已签发证书时，ARN 就会出现在 ACM 控制台中。
SECRET\$1ARN
使用 AWS Secrets Manager 创建的受支持密钥的 Amazon 资源名称（ARN）。有关如何创建和检索密钥的 ARN 的信息，请参阅《AWS Secrets Manager User Guide》**中的 [Manage secrets with AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)，以及[在 Amazon Redshift 中检索密钥的 Amazon 资源名称（ARN）](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-secrets-manager-integration-retrieving-secret.html)。
URI
Apache Kafka、Confluent Cloud 或 Amazon Managed Streaming for Apache Kafka（Amazon MSK）集群的引导 URL。端点必须可以从 Amazon Redshift 集群进行访问（路由）。有关更多信息，请参阅 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。
# ALTER EXTERNAL VIEW
使用 ALTER EXTERNAL VIEW 命令更新您的外部视图。根据您使用的参数，也可以引用此视图的其他 SQL 引擎（例如 Amazon Athena 和 Amazon EMR Spark）可能会受到影响。有关 Data Catalog 视图的更多信息，请参阅 [AWS Glue Data Catalog 视图](https://docs.aws.amazon.com/redshift/latest/dg/data-catalog-views-overview.html)。
## 语法
```
ALTER EXTERNAL VIEW schema_name.view_name
{catalog_name.schema_name.view_name | awsdatacatalog.dbname.view_name | external_schema_name.view_name}
[FORCE] { AS (query_definition) | REMOVE DEFINITION }
```
## 参数
*schema\$1name.view\$1name*
附加到 AWS Glue 数据库的架构，后面是视图的名称。
catalog\$1name.schema\$1name.view\$1name \$1 awsdatacatalog.dbname.view\$1name \$1 external\$1schema\$1name.view\$1name
更改视图时要使用的架构符号。可以指定使用您创建的 Glue 数据库 AWS Glue Data Catalog 或您创建的外部架构。有关更多信息，请参阅 [CREATE DATABASE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_DATABASE.html) 和 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。
FORCE
即使表中引用的对象与其他 SQL 引擎不一致，AWS Lake Formation 是否仍应更新视图的定义。如果 Lake Formation 更新了视图，其他 SQL 引擎就会认为该视图是过时的，直到这些引擎也更新为止。
*AS query\$1definition*
Amazon Redshift 为更改视图而运行的 SQL 查询的定义。
REMOVE DEFINITION
是否删除并重新创建视图。必须删除并重新创建视图才能将其标记为 `PROTECTED`。
## 示例
以下示例更改了名为 sample\$1schema.glue\$1data\$1catalog\$1view 的 Data Catalog 视图。
```
ALTER EXTERNAL VIEW sample_schema.glue_data_catalog_view
FORCE
REMOVE DEFINITION
```
# ALTER FUNCTION
重命名函数或者更改拥有者。函数名称和数据类型均为必需项。只有拥有者或超级用户可以重命名函数。只有超级用户可以更改函数的拥有者。
## 语法
```
ALTER FUNCTION function_name ( { [ py_arg_name py_arg_data_type | sql_arg_data_type } [ , ... ] ] )
RENAME TO new_name
```
```
ALTER FUNCTION function_name ( { [ py_arg_name py_arg_data_type | sql_arg_data_type } [ , ... ] ] )
OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
```
## 参数
*function\$1name*
要更改的函数的名称。指定当前搜索路径中函数的名称，或者通过格式 `schema_name.function_name` 使用特定架构。
*py\$1arg\$1name py\$1arg\$1data\$1type \$1 sql\$1arg\$1data\$1type*
可选。Python 用户定义函数的输入参数名称和数据类型的列表，或 SQL 用户定义函数的输入参数数据类型的列表。
*new\$1name*
用户定义函数的新名称。
*new\$1owner* \$1 CURRENT\$1USER \$1 SESSION\$1USER
用户定义函数的新拥有者。
## 示例
以下示例将函数的名称从 `first_quarter_revenue` 更改为 `quarterly_revenue`。
```
ALTER FUNCTION first_quarter_revenue(bigint, numeric, int)
RENAME TO quarterly_revenue;
```
以下示例将 `quarterly_revenue` 函数的拥有者更改为 `etl_user`。
```
ALTER FUNCTION quarterly_revenue(bigint, numeric) OWNER TO etl_user;
```
# ALTER GROUP
更改用户组。使用此命令可以将用户添加到组、从组中删除用户或重命名组。
## 语法
```
ALTER GROUP group_name
{
ADD USER username [, ... ] |
DROP USER username [, ... ] |
RENAME TO new_name
}
```
## 参数
*group\$1name*
要修改的用户组的名称。
ADD
将用户添加到用户组。
DROP
从用户组中删除用户。
*username*
要添加到组或从组中删除的用户的名称。
RENAME TO
重命名用户组。以两个下划线开头的组名保留供 Amazon Redshift 内部使用。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
*new\$1name*
用户组的新名称。
## 示例
以下示例将名为 DWUSER 的用户添加到 ADMIN\$1GROUP 组。
```
ALTER GROUP admin_group
ADD USER dwuser;
```
以下示例将组 ADMIN\$1GROUP 重命名为 ADMINISTRATORS。
```
ALTER GROUP admin_group
RENAME TO administrators;
```
以下示例将两个用户添加到组 ADMIN\$1GROUP。
```
ALTER GROUP admin_group
ADD USER u1, u2;
```
以下示例从 ADMIN\$1GROUP 组删除两个用户。
```
ALTER GROUP admin_group
DROP USER u1, u2;
```
# ALTER IDENTITY PROVIDER
更改身份提供者以分配新的参数和值。运行此命令时，先前设置的所有参数值都将在分配新值之前删除。只有超级用户可以更改身份提供者。
## 语法
```
ALTER IDENTITY PROVIDER identity_provider_name
[PARAMETERS parameter_string]
[NAMESPACE namespace]
[IAM_ROLE iam_role]
[AUTO_CREATE_ROLES
[ TRUE [ { INCLUDE | EXCLUDE } GROUPS LIKE filter_pattern] |
FALSE
]
[DISABLE | ENABLE]
```
## 参数
*identity\$1provider\$1name*
新身份提供者的名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
*parameter\$1string*
一个包含格式正确的 JSON 对象的字符串，其中包含特定身份提供者所需的参数和值。
*命名空间*
组织命名空间。
*iam\$1role*
提供连接到 IAM Identity Center 的权限的 IAM 角色。仅当身份提供者类型为 AWSIDC 时，此参数才适用。
*auto\$1create\$1roles*
启用或禁用自动创建角色特征。如果该值为 TRUE，则 Amazon Redshift 启用自动创建角色功能。如果该值为 FALSE，则 Amazon Redshift 禁用自动创建角色功能。如果未指定此参数的值，Amazon Redshift 将使用以下逻辑确定该值：
+ 如果提供了 `AUTO_CREATE_ROLES` 但未指定值，则该值设置为 TRUE。
+ 如果未提供 `AUTO_CREATE_ROLES` 且身份提供者为 AWSIDC，则该值设置为 FALSE。
+ 如果未提供 `AUTO_CREATE_ROLES` 且身份提供者为 Azure，则该值设置为 TRUE。
要包括组，请指定 `INCLUDE`。默认值为空，这意味着如果 `AUTO_CREATE_ROLES` 为开启，则包括所有组。
要排除组，请指定 `EXCLUDE`。默认值为空，这意味着如果 `AUTO_CREATE_ROLES` 为开启，则不排除任何组。
*filter\$1pattern*
一个有效的 UTF-8 字符表达式，具有与组名称匹配的模式。LIKE 选项执行区分大小写的匹配，支持以下模式匹配元字符：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/dg/r_ALTER_IDENTITY_PROVIDER.html)
如果 *filter\$1pattern* 不包含元字符，则模式仅表示字符串本身；在此情况下，LIKE 的行为与等于运算符相同。
*filter\$1pattern* 支持以下字符：
+ 大写和小写字母字符（A-Z 和 a-z）
+ 数字（0-9）
+ 以下特殊字符：
```
_ % ^ * + ? { } , $
```
*DISABLE 或 ENABLE*
开启或关闭身份提供者。默认值为 ENABLE。
## 示例
以下示例更改名为 *oauth\$1standard* 的身份提供者。它特别适用于 Microsoft Azure AD 作为身份提供者的情况。
```
ALTER IDENTITY PROVIDER oauth_standard
PARAMETERS '{"issuer":"https://sts.windows.net/2sdfdsf-d475-420d-b5ac-667adad7c702/",
"client_id":"87f4aa26-78b7-410e-bf29-57b39929ef9a",
"client_secret":"BUAH~ewrqewrqwerUUY^%tHe1oNZShoiU7",
"audience":["https://analysis.windows.net/powerbi/connector/AmazonRedshift"]
}'
```
以下示例显示了如何设置身份提供者命名空间。这可能适用于 Microsoft Azure AD（如果它遵循与上一个示例类似的语句），也可能适用于其它身份提供者。如果您通过托管应用程序设置了连接，则它也可能适用于将现有的 Amazon Redshift 预调配集群或 Amazon Redshift Serverless 工作组连接到 IAM Identity Center 的情况。
```
ALTER IDENTITY PROVIDER "my-redshift-idc-application"
NAMESPACE 'MYCO';
```
以下示例设置了 IAM 角色，并适用于配置 Redshift 与 IAM Identity Center 集成的使用案例。
```
ALTER IDENTITY PROVIDER "my-redshift-idc-application"
IAM_ROLE 'arn:aws:iam::123456789012:role/myadministratorrole';
```
有关设置从 Redshift 到 IAM Identity Center 的连接的更多信息，请参阅[将 Redshift 与 IAM Identity Center 连接，为用户提供单点登录体验](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-idp-connect.html)。
**禁用身份提供者**
以下示例语句显示了如何禁用身份提供者。禁用身份提供者后，身份提供者中的联合用户将无法登录集群，直至再次启用它。
```
ALTER IDENTITY PROVIDER "redshift-idc-app" DISABLE;
```
# ALTER MASKING POLICY
更改现有的动态数据掩蔽政策。有关动态数据掩蔽的更多信息，请参阅 [动态数据掩蔽](t_ddm.md)。
超级用户和具有 sys:secadmin 角色的用户或角色可以更改掩蔽政策。
## 语法
```
ALTER MASKING POLICY
{ policy_name | database_name.policy_name }
USING (masking_expression);
```
## 参数
*policy\$1name*
屏蔽策略的名称。此名称必须是数据库中已存在的掩蔽政策的名称。
database\$1name
从其中创建策略的数据库的名称。该数据库可以是连接的数据库，也可以是支持 Amazon Redshift 联合身份验证权限的数据库。
*masking\$1expression*
用于转换目标列的 SQL 表达式。可以使用诸如字符串操作函数之类的数据操作函数来编写该表达式，也可以与使用 SQL、Python 或 AWS Lambda 编写的用户定义函数结合使用。
表达式必须与原始表达式的输入列和数据类型相匹配。例如，如果原始掩蔽政策的输入列是 `sample_1 FLOAT` 和 `sample_2 VARCHAR(10)`，则您将无法更改掩蔽政策来使用第三列，也无法使该政策采用一个浮点数和一个布尔值。如果您使用常量作为掩蔽表达式，则必须将其显式转换为与输入类型匹配的类型。
您必须对在屏蔽表达式中使用的任何用户定义函数具有 USAGE 权限。
有关在 Amazon Redshift 联合身份验证权限目录上使用 ALTER MASKING POLICY 的信息，请参阅[使用 Amazon Redshift 联合身份验证权限管理访问控制](https://docs.aws.amazon.com/redshift/latest/dg/federated-permissions-managing-access.html)。
# ALTER MATERIALIZED VIEW
更改实体化视图的属性。
## 语法
```
ALTER MATERIALIZED VIEW mv_name
{
AUTO REFRESH { YES | NO }
| ALTER DISTKEY column_name
| ALTER DISTSTYLE ALL
| ALTER DISTSTYLE EVEN
| ALTER DISTSTYLE KEY DISTKEY column_name
| ALTER DISTSTYLE AUTO
| ALTER [COMPOUND] SORTKEY ( column_name [,...] )
| ALTER SORTKEY AUTO
| ALTER SORTKEY NONE
| ROW LEVEL SECURITY { ON | OFF } [ CONJUNCTION TYPE { AND | OR } ] [FOR DATASHARES]
};
```
## 参数
*mv\$1name*
要更改的实体化视图的名称。
AUTO REFRESH \$1 YES \$1 NO \$1
开启或关闭实体化视图的自动刷新的子句。有关自动刷新实体化视图的更多信息，请参阅[刷新实体化视图](materialized-view-refresh.md)。
ALTER DISTSTYLE ALL
用于将关系的现有分配方式更改为 `ALL` 的子句。请考虑以下事项：
+ 不能对同一个关系并发运行 ALTER DISTSTYLE、ALTER SORTKEY 和 VACUUM。
+ 如果 VACUUM 当前正在运行，则运行 ALTER DISTSTYLE ALL 将返回错误。
+ 如果 ALTER DISTSTYLE ALL 正在运行，则不对关系启动后台 vacuum。
+ 对于具有交错排序键和临时表的关系，不支持 ALTER DISTSTYLE ALL 命令。
+ 如果分配方式以前被定义为 AUTO，则关系不再是自动表优化的候选项。
有关 DISTSTYLE ALL 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
ALTER DISTSTYLE EVEN
用于将关系的现有分配方式更改为 `EVEN` 的子句。请考虑以下事项：
+ 不能对同一个关系并发运行 ALTER DISTSYTLE、ALTER SORTKEY 和 VACUUM。
+ 如果 VACUUM 当前正在运行，则运行 ALTER DISTSTYLE EVEN 将返回错误。
+ 如果 ALTER DISTSTYLE EVEN 正在运行，则不对关系启动后台 Vacuum。
+ 对于具有交错排序键和临时表的关系，不支持 ALTER DISTSTYLE EVEN 命令。
+ 如果分配方式以前被定义为 AUTO，则关系不再是自动表优化的候选项。
有关 DISTSTYLE EVEN 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
ALTER DISTKEY *column\$1name* 或 ALTER DISTSTYLE KEY DISTKEY *column\$1name*
一个子句，可更改用作关系的分配键的列。请考虑以下事项：
+ 不能对同一个关系并发运行 VACUUM 和 ALTER DISTKEY。
+ 如果 VACUUM 已经运行，则 ALTER DISTKEY 返回错误。
+ 如果 ALTER DISTKEY 正在运行，则不对关系启动后台 Vacuum。
+ 如果 ALTER DISTKEY 正在运行，则前台 vacuum 会返回错误。
+ 您一次只能对一个关系运行一个 ALTER DISTKEY 命令。
+ 具有交错排序键的关系不支持 ALTER DISTKEY 命令。
+ 如果分配方式以前被定义为 AUTO，则关系不再是自动表优化的候选项。
指定 DISTSTYLE KEY 时，按 DISTKEY 列中的值分配数据。有关 DISTSTYLE 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
ALTER DISTSTYLE AUTO
用于将关系的现有分配方式更改为 AUTO 的子句。
将分配方式更改为 AUTO 时，关系的分配方式设置为以下内容：
+ 带有 DISTSTYLE ALL 的小型关系被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE EVEN 的小型关系被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE KEY 的小型关系被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE ALL 的大型关系被转换为 AUTO(EVEN)。
+ 带有 DISTSTYLE EVEN 的大型关系被转换为 AUTO(EVEN)。
+ 带有 DISTSTYLE KEY 的大型关系被转换为 AUTO(KEY)，且保留 DISTKEY。在这种情况下，Amazon Redshift 不对关系进行任何更改。
如果 Amazon Redshift 确定新的分配方式或键将提高查询的性能，那么 Amazon Redshift 将来可能会更改关系的分配方式或键。例如，Amazon Redshift 可能会将 DISTSTYLE 为 AUTO(KEY) 的关系转换为 AUTO(EVEN)，反之亦然。有关分发键被更改时的行为的更多信息（包括数据重新分发和锁定），请转至 [Amazon Redshift Advisor 建议](https://docs.aws.amazon.com/redshift/latest/dg/advisor-recommendations.html#alter-diststyle-distkey-recommendation)。
有关 DISTSTYLE AUTO 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
要查看关系的分配方式，请查询 SVV\$1TABLE\$1INFO 系统目录视图。有关更多信息，请转至 [SVV\$1TABLE\$1INFO](r_SVV_TABLE_INFO.md)。要查看 Amazon Redshift Advisor 对关系的建议，请查询 SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS 系统目录视图。有关更多信息，请转至 [SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS](r_SVV_ALTER_TABLE_RECOMMENDATIONS.md)。要查看 Amazon Redshift 所采取的操作，请查询 SVL\$1AUTO\$1WORKER\$1ACTION 系统目录视图。有关更多信息，请转至 [SVL\$1AUTO\$1WORKER\$1ACTION](r_SVL_AUTO_WORKER_ACTION.md)。
ALTER [COMPOUND] SORTKEY ( *column\$1name* [,...] )
一个旨在更改或添加用于关系的排序键的子句。临时表不支持 ALTER SORTKEY。
当您更改排序键时，新排序键或原始排序键中列的压缩编码可能会更改。如果没有为关系显式定义编码，则 Amazon Redshift 按如下方式自动分配压缩编码：
+ 为定义为排序键的列分配 RAW 压缩。
+ 为定义为 BOOLEAN、REAL 或 DOUBLE PRECISION 数据类型的列分配 RAW 压缩。
+ 定义为 SMALLINT、INTEGER、BIGINT、DECIMAL、DATE、TIME、TIMETZT、IMESTAMP 或 TIMESTAMPTZ 的列分配了 AZ64 压缩。
+ 定义为 CHAR 或 VARCHAR 的列分配了 LZO 压缩。
请考虑以下事项：
+ 最多可以为每个关系的排序键定义 400 列。
+ 您可以将交错排序键更改为复合排序键或没有排序键。但是，您不能将复合排序键更改为交错排序键。
+ 如果排序键以前被定义为 AUTO，则关系不再是自动表优化的候选项。
+ Amazon Redshift 建议对定义为排序键的列使用 RAW 编码（不压缩）。当您更改列以将其选择为排序键时，列的压缩将更改为 RAW 压缩（无压缩）。这将增加关系所需的存储空间量。关系大小的增加程度取决于特定的关系定义和关系内容。有关压缩的更多信息，请转至[压缩编码](c_Compression_encodings.md)。
将数据加载到关系中时，将按照排序键的顺序加载数据。更改排序键时，Amazon Redshift 对数据重新排序。有关 SORTKEY 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
ALTER SORTKEY AUTO
一个用于将目标关系的排序键更改为或添加到 AUTO 的子句。临时表不支持 ALTER SORTKEY AUTO。
当您将排序键更改为 AUTO 时，Amazon Redshift 会保留关系的现有排序键。
如果 Amazon Redshift 确定新的排序键将提高查询的性能，那么 Amazon Redshift 将来可能会更改关系的排序键。
有关 SORTKEY AUTO 的更多信息，请转至 [CREATE MATERIALIZED VIEW](materialized-view-create-sql-command.md)。
要查看关系的排序键，请查询 SVV\$1TABLE\$1INFO 系统目录视图。有关更多信息，请转至 [SVV\$1TABLE\$1INFO](r_SVV_TABLE_INFO.md)。要查看 Amazon Redshift Advisor 对关系的建议，请查询 SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS 系统目录视图。有关更多信息，请转至 [SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS](r_SVV_ALTER_TABLE_RECOMMENDATIONS.md)。要查看 Amazon Redshift 所采取的操作，请查询 SVL\$1AUTO\$1WORKER\$1ACTION 系统目录视图。有关更多信息，请转至 [SVL\$1AUTO\$1WORKER\$1ACTION](r_SVL_AUTO_WORKER_ACTION.md)。
ALTER SORTKEY NONE
用于移除目标关系的排序键的子句。
如果排序键以前被定义为 AUTO，则关系不再是自动表优化的候选项。
ROW LEVEL SECURITY \$1 ON \$1 OFF \$1 [ CONJUNCTION TYPE \$1 AND \$1 OR \$1 ] [ FOR DATASHARES ]
一个对关系开启或关闭行级安全性的子句。
在为关系开启行级安全性后，您只能读取行级安全策略允许您访问的行。如果没有策略向您授予对关系的访问权限，您将看不到关系中的任何行。只有超级用户和拥有 `sys:secadmin` 角色的用户或角色才能设置 ROW LEVEL SECURITY 子句。有关更多信息，请参阅 [行级别安全性](t_rls.md)。
+ [ CONJUNCTION TYPE \$1 AND \$1 OR \$1 ]
一个允许您为关系选择行级安全策略的联接类型的子句。将多个行级安全策略附加到关系时，可以将这些策略与 AND 或 OR 子句合并。默认情况下，Amazon Redshift 将 RLS 策略与 AND 子句合并。具有 `sys:secadmin` 角色的超级用户、用户或角色可以使用此子句为关系定义行级安全策略的联接类型。有关更多信息，请参阅 [为每个用户组合多个策略](t_rls_combine_policies.md)。
+ FOR DATASHARES
一个子句，用于确定是否可以通过数据共享访问受 RLS 保护的关系。默认情况下，无法通过数据共享访问受 RLS 保护的关系。使用此子句运行的 ALTER MATERIALIZED VIEW ROW LEVEL SECURITY 命令只会影响关系的数据共享可访问性属性。ROW LEVEL SECURITY 属性未更改。
如果您允许通过数据共享访问受 RLS 保护的关系，则该关系在使用者端数据共享数据库中没有行级安全性。该关系在生产者端保留其 RLS 属性。
## 示例
以下示例启用要自动刷新的 `tickets_mv` 实体化视图。
```
ALTER MATERIALIZED VIEW tickets_mv AUTO REFRESH YES
```
# ALTER MATERIALIZED VIEW 的 DISTSTYLE 和 SORTKEY 示例
本主题中的示例向您展示了如何使用 ALTER MATERIAD VIEW 对 DISTYLE 和 SORTKEY 进行更改。
以下示例查询显示了如何使用示例基表更改 DISTSTYLE KEY DISTKEY 列：
```
CREATE TABLE base_inventory(
inv_date_sk int4 NOT NULL,
inv_item_sk int4 NOT NULL,
inv_warehouse_sk int4 NOT NULL,
inv_quantity_on_hand int4
);
INSERT INTO base_inventory VALUES(1,1,1,1);
CREATE materialized VIEW inventory diststyle even AS SELECT * FROM base_inventory;
SELECT "table", diststyle FROM svv_table_info WHERE "table" = 'inventory';
ALTER materialized VIEW inventory ALTER diststyle KEY distkey inv_warehouse_sk;
SELECT "table", diststyle FROM svv_table_info WHERE "table" = 'inventory';
ALTER materialized VIEW inventory ALTER distkey inv_item_sk;
SELECT "table", diststyle FROM svv_table_info WHERE "table" = 'inventory';
DROP TABLE base_inventory CASCADE;
```
将实体化视图更改为 DISTSTYLE ALL：
```
CREATE TABLE base_inventory(
inv_date_sk int4 NOT NULL,
inv_item_sk int4 NOT NULL,
inv_warehouse_sk int4 NOT NULL,
inv_quantity_on_hand int4
);
INSERT INTO base_inventory VALUES(1,1,1,1);
CREATE materialized VIEW inventory diststyle even AS SELECT * FROM base_inventory;
SELECT "table", diststyle FROM svv_table_info WHERE "table" = 'inventory';
ALTER MATERIALIZED VIEW inventory ALTER diststyle ALL;
SELECT "table", diststyle FROM svv_table_info WHERE "table" = 'inventory';
DROP TABLE base_inventory CASCADE;
```
以下命令显示了使用示例基表的 ALTER MATERIALIZED VIEW SORTKEY 示例：
```
CREATE TABLE base_inventory (c0 int, c1 int);
INSERT INTO base_inventory VALUES(1,1);
CREATE materialized VIEW inventory interleaved sortkey(c0, c1) AS SELECT * FROM base_inventory;
SELECT "table", sortkey1 FROM svv_table_info WHERE "table" = 'inventory';
ALTER materialized VIEW inventory ALTER sortkey(c0, c1);
SELECT "table", diststyle, sortkey_num FROM svv_table_info WHERE "table" = 'inventory';
ALTER materialized VIEW inventory ALTER sortkey NONE;
SELECT "table", diststyle, sortkey_num FROM svv_table_info WHERE "table" = 'inventory';
ALTER materialized VIEW inventory ALTER sortkey(c0);
SELECT "table", diststyle, sortkey_num FROM svv_table_info WHERE "table" = 'inventory';
DROP TABLE base_inventory CASCADE;
```
# ALTER RLS POLICY
更改表上现有的行级别安全性策略。
超级用户和具有 `sys:secadmin` 角色的用户或角色可以更改策略。
## 语法
```
ALTER RLS POLICY
{ policy_name | database_name.policy_name }
USING ( using_predicate_exp );
```
## 参数
*policy\$1name*
策略的名称。
database\$1name
从其中创建策略的数据库的名称。该数据库可以是连接的数据库，也可以是支持 Amazon Redshift 联合身份验证权限的数据库。
USING (* using\$1predicate\$1exp *)
指定应用于查询的 WHERE 子句的筛选器。Amazon Redshift 会在查询级别的用户谓词之前应用策略谓词。例如，**current\$1user = ‘joe’ and price > 10** 限制 Joe 只能查看价格高于 10 美元的记录。
该表达式可以访问在 CREATE RLS POLICY 语句的 WITH 子句中声明的变量，该语句用于创建名为 policy\$1name 的策略。
有关在 Amazon Redshift 联合身份验证权限目录上使用 ALTER RLS POLICY 的信息，请参阅[使用 Amazon Redshift 联合身份验证权限管理访问控制](https://docs.aws.amazon.com/redshift/latest/dg/federated-permissions-managing-access.html)。
## 示例
以下示例介绍了更改 RLS 策略。
```
-- First create an RLS policy that limits access to rows where catgroup is 'concerts'.
CREATE RLS POLICY policy_concerts
WITH (catgroup VARCHAR(10))
USING (catgroup = 'concerts');
-- Then, alter the RLS policy to only show rows where catgroup is 'piano concerts'.
ALTER RLS POLICY policy_concerts
USING (catgroup = 'piano concerts');
```
# ALTER ROLE
重命名角色或者更改拥有者。有关 Amazon Redshift 系统定义的角色列表，请参阅[Amazon Redshift 系统定义的角色](r_roles-default.md)。
## 所需的权限
以下是 ALTER ROLE 所需的权限：
+ Superuser
+ 具有 ALTER ROLE 权限的用户
## 语法
```
ALTER ROLE role [ WITH ]
{ { RENAME TO role } | { OWNER TO user_name } }[, ...]
[ EXTERNALID TO external_id ]
```
## 参数
*role*
要更改的角色的名称。
RENAME TO
角色的新名称。
OWNER TO *user\$1name*
角色的新拥有者。
EXTERNALID TO *external\$1id*
角色的新外部 ID，与身份提供者关联。有关更多信息，请参阅 [Amazon Redshift 的原生身份提供者 (IdP) 联合身份验证](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-native-idp.html)。
## 示例
以下示例将角色的名称从 `sample_role1` 更改为 `sample_role2`。
```
ALTER ROLE sample_role1 RENAME TO sample_role2;
```
以下示例将更改角色的拥有者。
```
ALTER ROLE sample_role1 WITH OWNER TO user1
```
ALTER ROLE 的语法与以下 ALTER PROCEDURE 类似。
```
ALTER PROCEDURE first_quarter_revenue(bigint, numeric) RENAME TO quarterly_revenue;
```
以下示例将过程的拥有者更改为 `etl_user`。
```
ALTER PROCEDURE quarterly_revenue(bigint, numeric) OWNER TO etl_user;
```
以下示例使用与身份提供者关联的新外部 ID 更新了角色 `sample_role1`。
```
ALTER ROLE sample_role1 EXTERNALID TO "XYZ456";
```
# ALTER PROCEDURE
重命名过程或者更改拥有者。需要过程名称和数据类型（或签名）。只有拥有者或超级用户可以重命名过程。只有超级用户可以更改过程的拥有者。
## 语法
```
ALTER PROCEDURE sp_name [ ( [ [ argname ] [ argmode ] argtype [, ...] ] ) ]
RENAME TO new_name
```
```
ALTER PROCEDURE sp_name [ ( [ [ argname ] [ argmode ] argtype [, ...] ] ) ]
OWNER TO { new_owner | CURRENT_USER | SESSION_USER }
```
## 参数
*sp\$1name*
要变更的过程的名称。只指定当前搜索路径中过程的名称，或者通过格式 `schema_name.sp_procedure_name` 使用特定 schema。
*[argname] [argmode] argtype*
参数名称、参数模式和数据类型的列表。只需要输入数据类型，这些数据类型用于标识存储过程。另外，您可以提供用于创建过程的完整签名，包括输入和输出参数及其模式。
*new\$1name*
存储过程的新名称。
*new\$1owner* \$1 CURRENT\$1USER \$1 SESSION\$1USER
存储过程的新拥有者。
## 示例
以下示例将过程的名称从 `first_quarter_revenue` 更改为 `quarterly_revenue`。
```
ALTER PROCEDURE first_quarter_revenue(volume INOUT bigint, at_price IN numeric,
result OUT int) RENAME TO quarterly_revenue;
```
此示例等效于以下内容：
```
ALTER PROCEDURE first_quarter_revenue(bigint, numeric) RENAME TO quarterly_revenue;
```
以下示例将过程的拥有者更改为 `etl_user`。
```
ALTER PROCEDURE quarterly_revenue(bigint, numeric) OWNER TO etl_user;
```
# ALTER SCHEMA
更改现有 schema 的定义。使用此命令可重命名 schema 或更改 schema 的所有者。例如，当您计划创建现有 schema 的新版本时，将现有 schema 重命名可保留该 schema 的备份副本。有关 schema 的更多信息，请参阅 [CREATE SCHEMA](r_CREATE_SCHEMA.md)。
要查看已配置的 schema 配额，请参阅[SVV\$1SCHEMA\$1QUOTA\$1STATE](r_SVV_SCHEMA_QUOTA_STATE.md)。
要查看已超出 schema 配额的记录，请参阅[STL\$1SCHEMA\$1QUOTA\$1VIOLATIONS](r_STL_SCHEMA_QUOTA_VIOLATIONS.md)。
## 所需的权限
以下是 ALTER SCHEMA 所需的权限：
+ Superuser
+ 具有 ALTER SCHEMA 权限的用户
+ Schema 拥有者
更改架构名称时，请注意，使用了旧名称的对象，例如存储过程或实体化视图，必须对其进行更新以使用新名称。
## 语法
```
ALTER SCHEMA schema_name
{
RENAME TO new_name |
OWNER TO new_owner |
QUOTA { quota [MB | GB | TB] | UNLIMITED }
}
```
## 参数
*schema\$1name*
要修改的数据库 schema 的名称。
RENAME TO
用于重命名 schema 的子句。
*new\$1name*
schema 的新名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
OWNER TO
用于更改 schema 所有者的子句。
*new\$1owner*
schema 的新所有者。
QUOTA
指定的 schema 可以使用的最大磁盘空间量。此空间是指定 schema 下所有表的整体大小。Amazon Redshift 将选定值转换为 MB。如果您未指定值，则 GB 是默认的测量单位。
有关配置 schema 配额的更多信息，请参阅[CREATE SCHEMA](r_CREATE_SCHEMA.md)。
## 示例
以下示例将 SALES schema 重命名为 US\$1SALES。
```
alter schema sales
rename to us_sales;
```
以下示例将 US\$1SALES schema 的所有权授予用户 DWUSER。
```
alter schema us_sales
owner to dwuser;
```
以下示例将配额更改为 300 GB 并删除此配额。
```
alter schema us_sales QUOTA 300 GB;
alter schema us_sales QUOTA UNLIMITED;
```
# ALTER SYSTEM
更改 Amazon Redshift 集群或 Redshift Serverless 工作组的系统级配置选项。
## 所需的权限
以下用户类型之一可以运行 ALTER SYSTEM 命令：
+ Superuser
+ 管理员用户
## 语法
```
ALTER SYSTEM SET system-level-configuration = {true| t | on | false | f | off}
```
## 参数
*system-level-configuration*
系统级配置。有效值：`data_catalog_auto_mount` 和 `metadata_security`。
\$1true\$1 t \$1 on \$1 false \$1 f \$1 off\$1
用于激活或停用系统级配置的值。`true`、`t` 或 `on` 表示要激活配置。`false`、`f` 或 `off` 表示要停用配置。
## 使用说明
对于预置集群，对 `data_catalog_auto_mount` 的更改将在集群下次重新引导时生效。有关更多信息，请参阅《Amazon Redshift 管理指南》**中的[重新引导集群](https://docs.aws.amazon.com/redshift/latest/mgmt/managing-clusters-console.html#reboot-cluster)。
对于无服务器工作组，对 `data_catalog_auto_mount` 的更改不会立即生效。
## 示例
以下示例开启了自动挂载 AWS Glue Data Catalog 的功能。
```
ALTER SYSTEM SET data_catalog_auto_mount = true;
```
以下示例开启了元数据安全性。
```
ALTER SYSTEM SET metadata_security = true;
```
### 设置默认身份命名空间
此示例特定于使用身份提供者。您可以将 Redshift 与 IAM Identity Center 和身份提供者集成，来集中管理 Redshift 和其它 AWS 服务的身份。
以下示例显示了如何为系统设置默认身份命名空间。这样做后，将可以更轻松地运行 GRANT 和 CREATE 语句，因为您不必包括此命名空间来作为每个身份的前缀。
```
ALTER SYSTEM SET default_identity_namespace = 'MYCO';
```
运行命令后，您可以运行如下语句：
```
GRANT SELECT ON TABLE mytable TO alice;
GRANT UPDATE ON TABLE mytable TO salesrole;
CREATE USER bob password 'md50c983d1a624280812631c5389e60d48c';
```
设置默认身份命名空间的效果是，每个身份都不需要将其作为前缀。在本例中，`alice` 替换为 `MYCO:alice`。如果包含任何身份，就会发生这种情况。有关将身份提供者与 Redshift 结合使用的更多信息，请参阅[将 Redshift 与 IAM Identity Center 连接，为用户提供单点登录体验](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-idp-connect.html)。
有关与 IAM Identity Center 的 Redshift 配置相关的设置的更多信息，请参阅 [SET](r_SET.md) 和 [ALTER IDENTITY PROVIDER](r_ALTER_IDENTITY_PROVIDER.md)。
# ALTER TABLE
此命令更改 Amazon Redshift 表或 Amazon Redshift Spectrum 外部表的定义。此命令更新 [CREATE TABLE](r_CREATE_TABLE_NEW.md) 或 [CREATE EXTERNAL TABLE](r_CREATE_EXTERNAL_TABLE.md) 设置的值和属性。您可以在视图上使用 ALTER TABLE 来实现行级别安全性（RLS）。
您不能在以下事务块内的外部表上运行 ALTER TABLE (BEGIN ... END)。有关事务的更多信息，请参阅 [Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
除非文档中明确规定可以在表更改时查询表或执行其他操作，否则 ALTER TABLE 会锁定表的读写操作，直到包含 ALTER TABLE 操作的事务完成。
## 所需的权限
修改表的用户需要适当的权限才能成功执行命令。根据具体的 ALTER TABLE 命令，需要以下权限之一。
+ Superuser
+ 具有 ALTER TABLE 权限的用户
+ 对模式拥有 USAGE 权限的表拥有者
## 语法
```
ALTER TABLE table_name
{
ADD table_constraint
| DROP CONSTRAINT constraint_name [ RESTRICT | CASCADE ]
| OWNER TO new_owner
| RENAME TO new_name
| RENAME COLUMN column_name TO new_name
| ALTER COLUMN column_name TYPE updated_varchar_data_type_size
| ALTER COLUMN column_name ENCODE new_encode_type
| ALTER COLUMN column_name ENCODE encode_type,
| ALTER COLUMN column_name ENCODE encode_type, .....;
| ALTER DISTKEY column_name
| ALTER DISTSTYLE ALL
| ALTER DISTSTYLE EVEN
| ALTER DISTSTYLE KEY DISTKEY column_name
| ALTER DISTSTYLE AUTO
| ALTER [COMPOUND] SORTKEY ( column_name [,...] )
| ALTER SORTKEY AUTO
| ALTER SORTKEY NONE
| ALTER ENCODE AUTO
| ADD [ COLUMN ] column_name column_type
[ DEFAULT default_expr ]
[ ENCODE encoding ]
[ NOT NULL | NULL ]
[ COLLATE { CASE_SENSITIVE | CS | CASE_INSENSITIVE | CI } ] |
| DROP [ COLUMN ] column_name [ RESTRICT | CASCADE ]
| ROW LEVEL SECURITY { ON | OFF } [ CONJUNCTION TYPE { AND | OR } ] [ FOR DATASHARES ]
| MASKING { ON | OFF } FOR DATASHARES }
where table_constraint is:
[ CONSTRAINT constraint_name ]
{ UNIQUE ( column_name [, ... ] )
| PRIMARY KEY ( column_name [, ... ] )
| FOREIGN KEY (column_name [, ... ] )
REFERENCES reftable [ ( refcolumn ) ]}
The following options apply only to external tables:
SET LOCATION { 's3://bucket/folder/' | 's3://bucket/manifest_file' }
| SET FILE FORMAT format |
| SET TABLE PROPERTIES ('property_name'='property_value')
| PARTITION ( partition_column=partition_value [, ...] )
SET LOCATION { 's3://bucket/folder' |'s3://bucket/manifest_file' }
| ADD [IF NOT EXISTS]
PARTITION ( partition_column=partition_value [, ...] ) LOCATION { 's3://bucket/folder' |'s3://bucket/manifest_file' }
[, ... ]
| DROP PARTITION ( partition_column=partition_value [, ...] )
```
要减少运行 ALTER TABLE 命令的时间，可以结合使用 ALTER TABLE 命令的一些子句。
Amazon Redshift 支持以下 ALTER TABLE 子句组合：
```
ALTER TABLE tablename ALTER SORTKEY (column_list), ALTER DISTKEY column_Id;
ALTER TABLE tablename ALTER DISTKEY column_Id, ALTER SORTKEY (column_list);
ALTER TABLE tablename ALTER SORTKEY (column_list), ALTER DISTSTYLE ALL;
ALTER TABLE tablename ALTER DISTSTYLE ALL, ALTER SORTKEY (column_list);
```
## 参数
*table\$1name*
要修改的表的名称。只指定表的名称，或者通过格式 *schema\$1name.table\$1name* 使用特定 schema。外部表必须通过一个外部 schema 名称进行限定。如果您使用 ALTER TABLE 语句重命名视图或更改其拥有者，您还可以指定视图名称。表名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。您可以使用 UTF-8 多字节字符，每个字符最多为四个字节。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
ADD *table\$1constraint*
用于将指定约束添加到表的子句。有关有效 *table\$1constraint* 值的描述，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
您不能将主键约束添加到可为空的列。如果列最初是使用 NOT NULL 约束创建的，您可以添加主键约束。
DROP CONSTRAINT *constraint\$1name*
用于从表中删除指定约束的子句。要删除约束，请指定约束名称而不是约束类型。要查看表约束名称，请运行以下查询。
```
select constraint_name, constraint_type
from information_schema.table_constraints;
```
RESTRICT
用于仅删除指定约束的子句。RESTRICT 是 DROP CONSTRAINT 的一个选项。RESTRICT 不能与 CASCADE 一起使用。
CASCADE
用于删除指定约束和依赖于该约束的任何内容的子句。CASCADE 是 DROP CONSTRAINT 的选项。CASCADE 不能与 RESTRICT 一起使用。
OWNER TO *new\$1owner*
用于将表（或视图）的所有者更改为 *new\$1owner* 值的子句。
RENAME TO *new\$1name*
用于将表（或视图）重命名为 *new\$1name* 中指定的值的子句。表名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。
您不能将永久表重命名为以“\$1”开头的表。名称以“\$1”开头的表是临时表。
您无法重命名外部表。
ALTER COLUMN *column\$1name* TYPE *updated\$1varchar\$1data\$1type\$1size*
这是一个更改定义为 VARCHAR 数据类型的列大小的子句。此子句仅支持修改 VARCHAR 数据类型的大小。请考虑以下限制：
+ 您无法修改具有 BYTEDICT、RUNLENGTH、TEXT255 或 TEXT32K 压缩编码的列。
+ 您无法将大小减少到小于现有数据的最大大小。
+ 您无法更改具有默认值的列。
+ 您无法更改具有 UNIQUE、PRIMARY KEY 或 FOREIGN KEY 的列。
+ 您不能更改以下事务块中的列：(BEGIN ... END)。有关事务的更多信息，请参阅 [Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
ALTER COLUMN *column\$1name* ENCODE *new\$1encode\$1type*
更改列的压缩编码的子句。如果为列指定压缩编码，则表不再设置为 ENCODE AUTO。有关压缩编码的信息，请参阅[列压缩，减小存储数据的大小](t_Compressing_data_on_disk.md)。
在更改列的压缩编码时，表仍可供查询。
请考虑以下限制：
+ 您不能将列更改为与当前为该列定义的相同的编码。
+ 不能使用交错排序键更改表中列的编码。
ALTER COLUMN *column\$1name* ENCODE *encode\$1type*, ALTER COLUMN *column\$1name* ENCODE *encode\$1type*, .....;
更改单个命令中多个列的压缩编码的子句。有关压缩编码的信息，请参阅[列压缩，减小存储数据的大小](t_Compressing_data_on_disk.md)。
在更改列的压缩编码时，表仍可供查询。
请考虑以下限制：
+ 您不能在单个命令中多次将列更改为相同或不同的编码类型。
+ 您不能将列更改为与当前为该列定义的相同的编码。
+ 不能使用交错排序键更改表中列的编码。
ALTER DISTSTYLE ALL
用于将表的现有分配样式更改为 `ALL` 的子句。请考虑以下事项：
+ ALTER DISTSTYLE、ALTER SORTKEY 和 VACUUM 不能同时对同一个表运行。
+ 如果 VACUUM 当前正在运行，则运行 ALTER DISTSTYLE ALL 将返回错误。
+ 如果 ALTER DISTSTYLE ALL 正在运行，则不在表上启动后台 vacuum。
+ 对于具有交错排序键和临时表的表，不支持 ALTER DISTSTYLE ALL 命令。
+ 如果分配方式以前被定义为 AUTO，则表不再是自动表优化的候选项。
有关 DISTSTYLE ALL 的更多信息，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
ALTER DISTSTYLE EVEN
用于将表的现有分配样式更改为 `EVEN` 的子句。请考虑以下事项：
+ ALTER DISTSYTLE、ALTER SORTKEY 和 VACUUM 不能同时对同一个表运行。
+ 如果 VACUUM 当前正在运行，则运行 ALTER DISTSTYLE EVEN 将返回错误。
+ 如果 ALTER DISTSTYLE EVEN 正在运行，则不在表上启动后台 Vacuum。
+ 对于具有交错排序键和临时表的表，不支持 ALTER DISTSTYLE EVEN 命令。
+ 如果分配方式以前被定义为 AUTO，则表不再是自动表优化的候选项。
有关 DISTSTYLE EVEN 的更多信息，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
ALTER DISTKEY *column\$1name* 或 ALTER DISTSTYLE KEY DISTKEY *column\$1name*
一个子句，可更改用作表的分配键的列。请考虑以下事项：
+ 不能在同一个表上并发运行 VACUUM 和 ALTER DISTKEY。
+ 如果 VACUUM 已经运行，则 ALTER DISTKEY 返回错误。
+ 如果 ALTER DISTKEY 正在运行，则不在表上启动后台 Vacuum。
+ 如果 ALTER DISTKEY 正在运行，则前台 vacuum 会返回错误。
+ 您一次只能在一个表上运行一个 ALTER DISTKEY 命令。
+ 具有交错排序键的表不支持 ALTER DISTKEY 命令。
+ 如果分配方式以前被定义为 AUTO，则表不再是自动表优化的候选项。
指定 DISTSTYLE KEY 时，按 DISTKEY 列中的值分配数据。有关 DISTSTYLE 的更多信息，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
ALTER DISTSTYLE AUTO
用于将表的现有分配方式更改为 AUTO 的子句。
将分配方式更改为 AUTO 时，表的分配模式设置为以下内容：
+ 带有 DISTSTYLE ALL 的小型表被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE EVEN 的小型表被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE KEY 的小型表被转换为 AUTO(ALL)。
+ 带有 DISTSTYLE ALL 的大型表被转换为 AUTO(EVEN)。
+ 带有 DISTSTYLE EVEN 的大型表被转换为 AUTO(EVEN)。
+ 带有 DISTSTYLE KEY 的大型表被转换为 AUTO(KEY)，且 DISTKEY 被保留。在这种情况下，Amazon Redshift 不对表进行任何更改。
如果 Amazon Redshift 确定新的分配方式或密钥将提高查询的性能，那么 Amazon Redshift 将来可能会更改您的表格的分配方式或键。例如，Amazon Redshift 可能会将 DISTSTYLE 为 AUTO(KEY) 的表转换为 AUTO(EVEN)，反之亦然。有关分发密钥被更改时行为的更多信息（包括数据重新分发和锁定），请参阅 [Amazon Redshift Advisor 建议](https://docs.aws.amazon.com/redshift/latest/dg/advisor-recommendations.html#alter-diststyle-distkey-recommendation)。
有关 DISTSTYLE AUTO 的更多信息，请参阅[CREATE TABLE](r_CREATE_TABLE_NEW.md)。
要查看表的分配方式，请查询 SVV\$1TABLE\$1INFO 系统目录视图。有关更多信息，请参阅 [SVV\$1TABLE\$1INFO](r_SVV_TABLE_INFO.md)。要查看 Amazon Redshift Advisor 对表的建议，请查询 SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS 系统目录视图。有关更多信息，请参阅 [SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS](r_SVV_ALTER_TABLE_RECOMMENDATIONS.md)。要查看 Amazon Redshift 所采取的操作，请查询 SVL\$1AUTO\$1WORKER\$1ACTION 系统目录视图。有关更多信息，请参阅 [SVL\$1AUTO\$1WORKER\$1ACTION](r_SVL_AUTO_WORKER_ACTION.md)。
ALTER [COMPOUND] SORTKEY ( *column\$1name* [,...] )
一个旨在更改或添加用于表的排序键的子句。临时表不支持 ALTER SORTKEY。
当您更改排序键时，新排序键或原始排序键中列的压缩编码可能会更改。如果没有为表显式定义编码，则 Amazon Redshift 按如下方式自动分配压缩编码：
+ 为定义为排序键的列分配 RAW 压缩。
+ 为定义为 BOOLEAN、REAL 或 DOUBLE PRECISION 数据类型的列分配 RAW 压缩。
+ 定义为 SMALLINT、INTEGER、BIGINT、DECIMAL、DATE、TIME、TIMETZT、IMESTAMP 或 TIMESTAMPTZ 的列分配了 AZ64 压缩。
+ 定义为 CHAR 或 VARCHAR 的列分配了 LZO 压缩。
请考虑以下事项：
+ 最多可以为每个表的排序键定义 400 列。
+ 您可以将交错排序键更改为复合排序键或没有排序键。但是，您不能将复合排序键更改为交错排序键。
+ 如果排序键以前被定义为 AUTO，则表不再是自动表优化的候选项。
+ Amazon Redshift 建议对定义为排序键的列使用 RAW 编码（不压缩）。当您更改列以将其选择为排序键时，列的压缩将更改为 RAW 压缩（无压缩）。这将增加表所需的存储空间。表大小的增加程度取决于特定的表定义和表格内容。有关压缩的更多信息，请参阅[压缩编码](c_Compression_encodings.md)
将数据加载到表中时，将按照排序键的顺序加载数据。更改排序键时，Amazon Redshift 对数据重新排序。有关 SORTKEY 的更多信息，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
ALTER SORTKEY AUTO
一个可更改目标表的排序键或将其添加到 AUTO 的子句。临时表不支持 ALTER SORTKEY AUTO。
当您将排序键更改为 AUTO 时，Amazon Redshift 会保留表的现有排序键。
如果 Amazon Redshift 确定新的排序键将提高查询的性能，那么 Amazon Redshift 将来可能会更改您的表的排序键。
有关 SORTKEY AUTO 的更多信息，请参阅[CREATE TABLE](r_CREATE_TABLE_NEW.md)。
要查看表的排序键，请查询 SVV\$1TABLE\$1INFO 系统目录视图。有关更多信息，请参阅 [SVV\$1TABLE\$1INFO](r_SVV_TABLE_INFO.md)。要查看 Amazon Redshift Advisor 对表的建议，请查询 SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS 系统目录视图。有关更多信息，请参阅 [SVV\$1ALTER\$1TABLE\$1RECOMMENDATIONS](r_SVV_ALTER_TABLE_RECOMMENDATIONS.md)。要查看 Amazon Redshift 所采取的操作，请查询 SVL\$1AUTO\$1WORKER\$1ACTION 系统目录视图。有关更多信息，请参阅 [SVL\$1AUTO\$1WORKER\$1ACTION](r_SVL_AUTO_WORKER_ACTION.md)。
ALTER SORTKEY NONE
删除目标表的排序键的子句。
如果排序键以前被定义为 AUTO，则表不再是自动表优化的候选项。
ALTER ENCODE AUTO
将目标表列的编码类型更改为 AUTO 的子句。当您将编码更改为 AUTO 时，Amazon Redshift 会保留表中列的现有编码类型。然后，如果 Amazon Redshift 确定新的编码类型可以提高查询性能，则 Amazon Redshift 可以更改表列的编码类型。
如果您更改一个或多个列以指定编码，Amazon Redshift 将不再自动调整表中所有列的编码。这些列保留当前的编码设置。
以下操作不会影响表的 ENCODE AUTO 设置：
+ 重命名表。
+ 更改表的 DISTSTYLE 或 SORTKEY 设置。
+ 使用 ENCODE 设置添加或删除列。
+ 使用 COPY 命令的 COMPUPDATE 选项。有关更多信息，请参阅 [数据加载操作](copy-parameters-data-load.md)。
要查看表的编码，请查询 SVV\$1TABLE\$1INFO 系统目录视图。有关更多信息，请参阅 [SVV\$1TABLE\$1INFO](r_SVV_TABLE_INFO.md)。
RENAME COLUMN *column\$1name* TO *new\$1name*
用于将列重命名为 *new\$1name* 中指定的值的子句。列名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
ADD [ COLUMN ] *column\$1name*
用于将具有指定名称的列添加到表的子句。您在每个 ALTER TABLE 语句中只能修改一列。
您无法添加用作表的分配键 (DISTKEY) 或排序键 (SORTKEY) 的列。
您不能使用 ALTER TABLE ADD COLUMN 命令修改以下表和列属性：
+ UNIQUE
+ PRIMARY KEY
+ REFERENCES（外键）
+ IDENTITY 或 GENERATED BY DEFAULT AS IDENTITY
列名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。可在单个表中定义的列的最大数目为 1,600。
在将列添加到外部表时，会应用以下限制：
+ 您无法向列约束为 DEFAULT、ENCODE、NOT NULL 或 NULL 的外部表中添加列。
+ 您无法向使用 AVRO 文件格式定义的外部表中添加列。
+ 如果启用 pseudocolumns，则可在单个表中定义的最大列数为 1,598。如果未启用 pseudocolumns，则可在单个表中定义的最大列数为 1600。
有关更多信息，请参阅 [CREATE EXTERNAL TABLE](r_CREATE_EXTERNAL_TABLE.md)。
*column\$1type*
要添加的列的数据类型。对于 CHAR 和 VARCHAR 列，您可以使用 MAX 关键字而不是声明最大长度。MAX 将最大长度设置为 4096 字节（对于 CHAR）或 65535 字节（对于 VARCHAR）。GEOMETRY 对象的最大大小为 1048447 字节。
有关 Amazon Redshift 支持的数据类型的信息，请参阅[数据类型](c_Supported_data_types.md)。
DEFAULT *default\$1expr*
用于为列分配默认数据值的子句。*default\$1expr* 的数据类型必须匹配列的数据类型。DEFAULT 值必须是无变量的表达式。不允许子查询、对当前表中其他列的交叉引用和用户定义的函数。
*default\$1expr* 在未为列指定值的任何 INSERT 操作中使用。如果未指定默认值，则列的默认值为 null。
如果 COPY 操作在具有 DEFAULT 值和 NOT NULL 约束的列上遇到空字段，则 COPY 命令将插入 *default\$1expr* 值。
外部表不支持 DEFAULT。
ENCODE *encoding*
列的压缩编码。预设情况下，如果您没有为表中的任何列指定压缩编码，或者您为表指定了 ENCODE AUTO 选项，Amazon Redshift 会自动管理表中所有列的压缩编码。
如果您为表中的任何列指定压缩编码，或者您没有为表指定 ENCODE AUTO 选项，Amazon Redshift 会自动将压缩编码分配给您未指定压缩编码的列，如下所示：
+ 默认情况下，会为临时表中的所有列分配 RAW 压缩。
+ 为定义为排序键的列分配 RAW 压缩。
+ 定义为 BOOLEAN、REAL、DOUBLE PRECISION、GEOMETRY 或 GEOGRAPHY 数据类型的列分配了 RAW 压缩。
+ 定义为 SMALLINT、INTEGER、BIGINT、DECIMAL、DATE、TIME、TIMETZ、TIMESTAMP 或 TIMESTAMPTZ 的列分配了 AZ64 压缩。
+ 定义为 CHAR、VARCHAR 或 VARBYTE 的列分配了 LZO 压缩。
如果您不希望压缩某个列，请显式指定 RAW 编码。
支持以下[compression encodings](c_Compression_encodings.md#compression-encoding-list)：
+ AZ64
+ BYTEDICT
+ DELTA
+ DELTA32K
+ LZO
+ MOSTLY8
+ MOSTLY16
+ MOSTLY32
+ RAW（无压缩）
+ RUNLENGTH
+ TEXT255
+ TEXT32K
+ ZSTD
外部表不支持 ENCODE。
NOT NULL \$1 NULL
NOT NULL 指定列中不允许包含 null 值。NULL（默认值）指定列接受 null 值。
外部表不支持 NOT NULL 和 NULL。
COLLATE \$1 CASE\$1SENSITIVE \$1 CS \$1 CASE\$1INSENSITIVE \$1 CI \$1
指定列中的字符串搜索或比较是区分大小写还是不区分大小写的子句。默认值与数据库的当前区分大小写的配置相同。
要查找数据库排序规则信息，请使用以下命令：
```
SELECT db_collation();
db_collation
----------------
case_sensitive
(1 row)
```
CASE\$1SENSITIVE 和 CS 可以互换，生成的结果相同。同样，CASE\$1INSENSITIVE 和 CI 可以互换，生成的结果相同。
DROP [ COLUMN ] *column\$1name*
要从表中删除的列的名称。
您无法删除表中的最后一列。表必须有至少一列。
您无法删除用作表的分配键 (DISTKEY) 或排序键 (SORTKEY) 的列。如果列具有任何从属对象，例如视图、主键、外键或 UNIQUE 限制，则 DROP COLUMN 的默认行为是 RESTRICT。
对外部表中的列执行 DROP 时，会应用以下限制：
+ 如果列用作分区，则您无法哦那个外部表中删除列。
+ 您无法从使用 AVRO 文件格式定义的外部表中删除列。
+ 对于外部表，将会忽略 RESTRICT 和 CASCADE。
+ 除非删除或分离策略，否则您无法删除策略定义中引用的策略表中的列。在指定 CASCADE 选项时，这也将适用。您可以删除策略表中的其他列。
有关更多信息，请参阅 [CREATE EXTERNAL TABLE](r_CREATE_EXTERNAL_TABLE.md)。
RESTRICT
在下面这些情况下，与 DROP COLUMN 一起使用时，RESTRICT 表示不删除要删除的列：
+ 定义的视图引用了要删除的列
+ 外键引用了该列
+ 该列参与了多部分键
RESTRICT 不能与 CASCADE 一起使用。
对于外部表，将会忽略 RESTRICT 和 CASCADE。
CASCADE
在与 DROP COLUMN 配合使用时，删除指定的列以及依赖该列的任何内容。CASCADE 不能与 RESTRICT 一起使用。
对于外部表，将会忽略 RESTRICT 和 CASCADE。
以下选项仅适用于外部表。
SET LOCATION \$1 's3://*bucket/folder*/' \$1 's3://*bucket/manifest\$1file*' \$1
包含数据文件的 Amazon S3 文件夹的路径或包含 Amazon S3 对象路径列表的清单文件。桶必须与 Amazon Redshift 集群位于同一 AWS 区域。有关受支持的 AWS 区域的列表，请参阅[Amazon Redshift Spectrum 限制](c-spectrum-considerations.md)。有关使用清单文件的更多信息，请参阅 CREATE EXTERNAL TABLE [参数](r_CREATE_EXTERNAL_TABLE.md#r_CREATE_EXTERNAL_TABLE-parameters) 参考中的 LOCATION。
SET FILE FORMAT *format*
外部数据文件的文件格式。
有效格式如下所示：
+ AVRO
+ PARQUET
+ RCFILE
+ SEQUENCEFILE
+ TEXTFILE
SET TABLE PROPERTIES ( '*property\$1name*'='*property\$1value*')
一个子句，用于设置外部表的表属性的表定义。
表属性区分大小写。
'numRows'='*row\$1count*'
用于为表定义设置 numRows 值的属性。若要显式更新外部表的统计数据，请设置 numRows 属性来指示表的大小。Amazon Redshift 不分析外部表来生成表统计数据，查询优化程序会使用这些统计数据来生成查询计划。如果没有为外部表设置表统计数据，则 Amazon Redshift 会生成查询执行计划。此计划是基于“外部表较大，本地表较小”的假设生成的。
'skip.header.line.count'='*line\$1count*'
用于设置在每个源文件开头要跳过的行数的属性。
PARTITION ( *partition\$1column*=*partition\$1value* [, ...] SET LOCATION \$1 's3://*bucket*/*folder*' \$1 's3://*bucket*/*manifest\$1file*' \$1
用于为一个或多个分区列设置新位置的子句。
ADD [ IF NOT EXISTS ] PARTITION ( *partition\$1column*=*partition\$1value* [, ...] ) LOCATION \$1 's3://*bucket*/*folder*' \$1 's3://*bucket*/*manifest\$1file*' \$1 [, ... ]
用于添加一个或多个分区的子句。您可以使用单个 ALTER TABLE … ADD 语句指定多个 PARTITION 子句。
如果使用 AWS Glue 目录，则可以使用单个 ALTER TABLE 语句最多添加 100 个分区。
IF NOT EXISTS 子句指示，如果指定的分区已存在，命令应不进行任何更改。它还指示该命令应返回分区存在的消息，而不是以错误终止。此子句在编写脚本时很有用，可使脚本在 ALTER TABLE 尝试添加已存在的分区时不会失败。
DROP PARTITION (*partition\$1column*=*partition\$1value* [, ...] )
用于删除指定分区的子句。删除分区只会更改外部表元数据。Amazon S3 上的数据不受影响。
ROW LEVEL SECURITY \$1 ON \$1 OFF \$1 [ CONJUNCTION TYPE \$1 AND \$1 OR \$1 ] [ FOR DATASHARES ]
一个对关系开启或关闭行级安全性的子句。
在为关系开启行级安全性后，您只能读取行级安全策略允许您访问的行。如果没有策略向您授予对关系的访问权限，您将看不到关系中的任何行。只有超级用户和拥有 `sys:secadmin` 角色的用户或角色才能设置 ROW LEVEL SECURITY 子句。有关更多信息，请参阅 [行级别安全性](t_rls.md)。连接的数据库或具有 Amazon Redshift 联合身份验证权限的数据库支持此语句。具有 Amazon Redshift 联合身份验证权限的数据库不支持 FOR DATASHARES 子句。
+ [ CONJUNCTION TYPE \$1 AND \$1 OR \$1 ]
一个允许您为关系选择行级安全策略的联接类型的子句。将多个行级安全策略附加到关系时，可以将这些策略与 AND 或 OR 子句合并。默认情况下，Amazon Redshift 将 RLS 策略与 AND 子句合并。具有 `sys:secadmin` 角色的超级用户、用户或角色可以使用此子句为关系定义行级安全策略的联接类型。有关更多信息，请参阅 [为每个用户组合多个策略](t_rls_combine_policies.md)。
+ FOR DATASHARES
一个子句，用于确定是否可以通过数据共享访问受 RLS 保护的关系。默认情况下，无法通过数据共享访问受 RLS 保护的关系。使用此子句运行的 ALTER TABLE ROW LEVEL SECURITY 命令只会影响关系的数据共享可访问性属性。ROW LEVEL SECURITY 属性未更改。
如果您允许通过数据共享访问受 RLS 保护的关系，则该关系在使用者端数据共享数据库中没有行级安全性。该关系在生产者端保留其 RLS 属性。
MASKING \$1 ON \$1 OFF \$1 FOR DATASHARES
一个子句，用于确定是否可以通过数据共享访问受 DDM 保护的关系。默认情况下，无法通过数据共享访问受 DDM 保护的关系。如果您使受 DDM 保护的关系可通过数据共享进行访问，则该关系在使用者端数据共享数据库中不会具有掩蔽保护。该关系在生产者端保留其掩蔽属性。只有超级用户和拥有 `sys:secadmin` 角色的用户或角色才能设置 MASKING FOR DATASHARES 子句。有关更多信息，请参阅 [动态数据掩蔽](t_ddm.md)。
## 示例
有关说明 ALTER TABLE 命令用法的示例，请参阅以下内容。
+ [ALTER TABLE 示例](r_ALTER_TABLE_examples_basic.md)
+ [ALTER EXTERNAL TABLE 示例](r_ALTER_TABLE_external-table.md)
+ [ALTER TABLE ADD 和 DROP COLUMN 示例](r_ALTER_TABLE_COL_ex-add-drop.md)
# ALTER TABLE 示例
以下示例演示了 ALTER TABLE 命令的基本用法。
## 重命名表或视图
以下命令将 USERS 表重命名为 USERS\$1BKUP：
```
alter table users
rename to users_bkup;
```
您还可以使用此类型的命令来重命名视图。
## 更改表或视图的所有者
以下命令将 VENUE 表所有者更改为用户 DWUSER：
```
alter table venue
owner to dwuser;
```
以下命令创建一个视图，然后更改其所有者：
```
create view vdate as select * from date;
alter table vdate owner to vuser;
```
## 重命名列
以下命令将 VENUE 表中的 VENUESEATS 列重命名为 VENUESIZE：
```
alter table venue
rename column venueseats to venuesize;
```
## 删除表约束
要删除表约束（例如主键、外键或唯一约束），请先查找约束的内部名称。然后在 ALTER TABLE 命令中指定约束名称。以下示例查找 CATEGORY 表的约束，然后删除名为 `category_pkey` 的主键。
```
select constraint_name, constraint_type
from information_schema.table_constraints
where constraint_schema ='public'
and table_name = 'category';
constraint_name | constraint_type
----------------+----------------
category_pkey | PRIMARY KEY
alter table category
drop constraint category_pkey;
```
## 更改 VARCHAR 列
为了节省存储空间，您最初可以使用 VARCHAR 列定义一个表，这些列具有满足当前数据要求所需的最小大小。以后，要容纳更长的字符串，您可以更改表以增加列大小。
以下示例将 EVENTNAME 列大小增加到 VARCHAR(300)。
```
alter table event alter column eventname type varchar(300);
```
## 更改 VARBYTE 列
为了节省存储空间，您最初可以使用 VARBYTE 列定义一个表，这些列具有满足当前数据要求所需的最小大小。以后，要容纳更长的字符串，您可以更改表以增加列大小。
以下示例将 EVENTNAME 列大小增加到 VARBYTE(300)。
```
alter table event alter column eventname type varbyte(300);
```
## 更改列的压缩编码
您可以更改列的压缩编码。您可以在下面找到一组演示此方法的示例。这些示例的表定义如下。
```
create table t1(c0 int encode lzo, c1 bigint encode zstd, c2 varchar(16) encode lzo, c3 varchar(32) encode zstd);
```
以下语句将列 c0 的压缩编码从 LZO 编码更改为 AZ64 编码。
```
alter table t1 alter column c0 encode az64;
```
以下语句将列 c1 的压缩编码从 Zstandard 编码更改为 AZ64 编码。
```
alter table t1 alter column c1 encode az64;
```
以下语句将列 c2 的压缩编码从 LZO 编码更改为 Byte-dictionary 编码。
```
alter table t1 alter column c2 encode bytedict;
```
以下语句将列 c3 的压缩编码从 Zstandard 编码更改为 Runlength 编码。
```
alter table t1 alter column c3 encode runlength;
```
## 修改 DISTSTYLE KEY DISTKEY 列
以下示例显示如何更改表的 DISTSTYLE 和 DISTKEY。
使用 EVEN 分配样式创建表 SVV\$1TABLE\$1INFO 视图显示 DISTSTYLE 为 EVEN。
```
create table inventory(
inv_date_sk int4 not null ,
inv_item_sk int4 not null ,
inv_warehouse_sk int4 not null ,
inv_quantity_on_hand int4
) diststyle even;
Insert into inventory values(1,1,1,1);
select "table", "diststyle" from svv_table_info;
table | diststyle
-----------+----------------
inventory | EVEN
```
将表 DISTKEY 更改为 `inv_warehouse_sk`。SVV\$1TABLE\$1INFO 视图将 `inv_warehouse_sk` 列显示为结果分配密钥。
```
alter table inventory alter diststyle key distkey inv_warehouse_sk;
select "table", "diststyle" from svv_table_info;
table | diststyle
-----------+-----------------------
inventory | KEY(inv_warehouse_sk)
```
将表 DISTKEY 更改为 `inv_item_sk`。SVV\$1TABLE\$1INFO 视图将 `inv_item_sk` 列显示为结果分配密钥。
```
alter table inventory alter distkey inv_item_sk;
select "table", "diststyle" from svv_table_info;
table | diststyle
-----------+-----------------------
inventory | KEY(inv_item_sk)
```
## 将表更改为 DISTSTYLE ALL
以下示例演示如何将表更改为 DISTSTYLE ALL。
使用 EVEN 分配样式创建表 SVV\$1TABLE\$1INFO 视图显示 DISTSTYLE 为 EVEN。
```
create table inventory(
inv_date_sk int4 not null ,
inv_item_sk int4 not null ,
inv_warehouse_sk int4 not null ,
inv_quantity_on_hand int4
) diststyle even;
Insert into inventory values(1,1,1,1);
select "table", "diststyle" from svv_table_info;
table | diststyle
-----------+----------------
inventory | EVEN
```
将表 DISTSTYLE 更改为 ALL。SVV\$1TABLE\$1INFO 视图显示已更改的 DISTSYTLE。
```
alter table inventory alter diststyle all;
select "table", "diststyle" from svv_table_info;
table | diststyle
-----------+----------------
inventory | ALL
```
## 更改表 SORTKEY
您可以将表更改为具有复合排序键或没有排序键。
在以下表定义中，表 `t1` 是使用交错排序键定义的。
```
create table t1 (c0 int, c1 int) interleaved sortkey(c0, c1);
```
以下命令将表从交错排序键更改为复合排序键。
```
alter table t1 alter sortkey(c0, c1);
```
以下命令对表进行了修改，删除了交错排序键。
```
alter table t1 alter sortkey none;
```
在以下表定义中，表 `t1` 将列 `c0` 定义为排序键。
```
create table t1 (c0 int, c1 int) sortkey(c0);
```
以下命令将表 `t1` 更改为复合排序键。
```
alter table t1 alter sortkey(c0, c1);
```
## 将表更改为 ENCODE AUTO
以下示例说明如何将表更改为 ENCODE AUTO。
此示例的表定义如下。列 `c0` 使用编码类型 AZ64 进行定义，列 `c1` 使用编码类型 LZO 定义。
```
create table t1(c0 int encode AZ64, c1 varchar encode LZO);
```
对于此表，以下语句将编码更改为 AUTO。
```
alter table t1 alter encode auto;
```
以下示例说明如何将表更改为删除 ENCODE AUTO 设置。
此示例的表定义如下。表列没有定义编码。在这种情况下，编码默认为 ENCODE AUTO。
```
create table t2(c0 int, c1 varchar);
```
对于此表，以下语句将 c0 列的编码更改为 LZO。表编码不再设置为 ENCODE AUTO。
```
alter table t2 alter column c0 encode lzo;;
```
## 修改行级别安全性控制
以下命令将对表关闭 RLS：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY OFF;
```
以下命令将对表开启 RLS：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY ON;
```
以下命令将对表开启 RLS，使其可通过数据共享进行访问：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY ON;
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY FOR DATASHARES OFF;
```
以下命令将对表开启 RLS，使其无法通过数据共享进行访问：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY ON;
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY FOR DATASHARES ON;
```
以下命令将对表开启 RLS，并将表的 RLS 联接类型设置为 OR：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY ON CONJUNCTION TYPE OR;
```
以下命令将对表开启 RLS，并将表的 RLS 联接类型设置为 AND：
```
ALTER TABLE tickit_category_redshift ROW LEVEL SECURITY ON CONJUNCTION TYPE AND;
```
# ALTER EXTERNAL TABLE 示例
以下示例使用位于美国东部（弗吉尼亚州北部）区域（`us-east-1`）AWS 区域的 Amazon S3 存储桶，以及在 [示例](r_CREATE_EXTERNAL_TABLE_examples.md) 中为 CREATE TABLE 创建的示例表。有关如何将分区与外部表一起使用的更多信息，请参阅[对 Redshift Spectrum 外部表进行分区](c-spectrum-external-tables.md#c-spectrum-external-tables-partitioning)。
以下示例将 SPECTRUM.SALES 外部表的 numRows 表属性设置为 170000 行。
```
alter table spectrum.sales
set table properties ('numRows'='170000');
```
以下示例更改 SPECTRUM.SALES 外部表的位置。
```
alter table spectrum.sales
set location 's3://redshift-downloads/tickit/spectrum/sales/';
```
以下示例将 SPECTRUM.SALES 外部表的格式更改为 Parquet。
```
alter table spectrum.sales
set file format parquet;
```
以下示例为表 SPECTRUM.SALES\$1PART 添加一个分区。
```
alter table spectrum.sales_part
add if not exists partition(saledate='2008-01-01')
location 's3://redshift-downloads/tickit/spectrum/sales_partition/saledate=2008-01/';
```
以下示例为表 SPECTRUM.SALES\$1PART 添加三个分区。
```
alter table spectrum.sales_part add if not exists
partition(saledate='2008-01-01')
location 's3://redshift-downloads/tickit/spectrum/sales_partition/saledate=2008-01/'
partition(saledate='2008-02-01')
location 's3://redshift-downloads/tickit/spectrum/sales_partition/saledate=2008-02/'
partition(saledate='2008-03-01')
location 's3://redshift-downloads/tickit/spectrum/sales_partition/saledate=2008-03/';
```
以下示例修改 SPECTRUM.SALES\$1PART 以删除包含 `saledate='2008-01-01''` 的分区。
```
alter table spectrum.sales_part
drop partition(saledate='2008-01-01');
```
以下示例为包含 `saledate='2008-01-01'` 的分区设置新的 Amazon S3 路径。
```
alter table spectrum.sales_part
partition(saledate='2008-01-01')
set location 's3://redshift-downloads/tickit/spectrum/sales_partition/saledate=2008-01-01/';
```
以下示例将 `sales_date` 的名称更改为 `transaction_date`。
```
alter table spectrum.sales rename column sales_date to transaction_date;
```
以下示例将列映射设置为使用优化行列式 (ORC) 格式的外部表的位置映射。
```
alter table spectrum.orc_example
set table properties('orc.schema.resolution'='position');
```
以下示例将列映射设置为使用 ORC 格式的外部表的名称映射。
```
alter table spectrum.orc_example
set table properties('orc.schema.resolution'='name');
```
# ALTER TABLE ADD 和 DROP COLUMN 示例
以下示例演示如何使用 ALTER TABLE 添加基本表列，然后删除该列；另外还演示如何删除具有从属对象的列。
## 添加基本列，然后删除该列
以下示例将独立 FEEDBACK\$1SCORE 列添加到 USERS 表。该列只包含一个整数，并且该列的默认值为 NULL（无反馈分数）。
首先，查询 PG\$1TABLE\$1DEF 目录表以查看 USERS 表的架构：
```
column | type | encoding | distkey | sortkey
--------------+------------------------+----------+---------+--------
userid | integer | delta | true | 1
username | character(8) | lzo | false | 0
firstname | character varying(30) | text32k | false | 0
lastname | character varying(30) | text32k | false | 0
city | character varying(30) | text32k | false | 0
state | character(2) | bytedict | false | 0
email | character varying(100) | lzo | false | 0
phone | character(14) | lzo | false | 0
likesports | boolean | none | false | 0
liketheatre | boolean | none | false | 0
likeconcerts | boolean | none | false | 0
likejazz | boolean | none | false | 0
likeclassical | boolean | none | false | 0
likeopera | boolean | none | false | 0
likerock | boolean | none | false | 0
likevegas | boolean | none | false | 0
likebroadway | boolean | none | false | 0
likemusicals | boolean | none | false | 0
```
现在添加 feedback\$1score 列：
```
alter table users
add column feedback_score int
default NULL;
```
从 USERS 中选择 FEEDBACK\$1SCORE 列以验证该列已添加：
```
select feedback_score from users limit 5;
feedback_score
----------------
NULL
NULL
NULL
NULL
NULL
```
删除该列以恢复原始 DDL：
```
alter table users drop column feedback_score;
```
## 删除具有从属对象的列
以下示例删除具有从属对象的列。结果是，同时删除从属对象。
开始时，将 FEEDBACK\$1SCORE 列重新添加到 USERS 表：
```
alter table users
add column feedback_score int
default NULL;
```
接下来，从名为 USERS\$1VIEW 的 USERS 表创建一个视图：
```
create view users_view as select * from users;
```
现在，尝试从 USERS 表中删除 FEEDBACK\$1SCORE 列。此 DROP 语句使用默认行为 (RESTRICT)：
```
alter table users drop column feedback_score;
```
Amazon Redshift 显示一条错误消息，说明由于另一个对象依赖该列而无法删除该列。
重新尝试删除 FEEDBACK\$1SCORE 列，这次指定 CASCADE 以删除所有从属对象：
```
alter table users
drop column feedback_score cascade;
```
# ALTER TABLE APPEND
通过从现有的源表移动数据，将行附加到目标表。源表中的数据将移到目标表中的匹配列。列的顺序不重要。在成功将数据附加到目标表后，源表变成空表。由于是移动数据而不是复制数据，因此相比类似的 [CREATE TABLE AS](r_CREATE_TABLE_AS.md) 或 [INSERT](r_INSERT_30.md) INTO 操作，ALTER TABLE APPEND 通常要快得多。
**注意**
ALTER TABLE APPEND 在源表和目标表之间移动数据块。为了提高性能，ALTER TABLE APPEND 不作为 append 操作的一部分压缩存储。因此，存储使用率会临时增加。要回收空间，请运行 [VACUUM](r_VACUUM_command.md) 操作。
同名的列还必须具有相同的列属性。如果源表包含目标表中不存在的列（反之亦然），请使用 IGNOREEXTRA 或 FILLTARGET 参数来指定如何管理额外的列。
您不能附加身份列。如果两个表中均包括身份列，则命令会失败。如果只有一个表具有标识列，请包含 FILLTARGET 或 IGNOREEXTRA 参数。有关更多信息，请参阅 [ALTER TABLE APPEND 使用说明](#r_ALTER_TABLE_APPEND_usage)。
您可以附加 GENERATED BY DEFAULT AS IDENTITY 列。您可以使用您提供的值来更新定义为 GENERATED BY DEFAULT AS IDENTITY 的列。有关更多信息，请参阅 [ALTER TABLE APPEND 使用说明](#r_ALTER_TABLE_APPEND_usage)。
目标表必须是永久表。但是，源可以是永久表，也可以是配置为流式摄取的实体化视图。如果一个对象定义了分配方式和分配键，则两个对象必须使用相同的分配方式和分配键。如果对对象进行排序，则两个对象必须使用相同的排序方式并定义相同的列作为排序键。
在操作完成之后，ALTER TABLE APPEND 会立即自动提交。该命令不能回滚。您不能在事务数据块 (BEGIN ... END) 中运行 ALTER TABLE APPEND。有关事务的更多信息，请参阅 [Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
## 所需的权限
根据具体的 ALTER TABLE APPEND 命令，需要以下权限之一：
+ Superuser
+ 具有 ALTER TABLE 系统权限的用户
+ 具有源表的 DELETE 和 SELECT 权限以及目标表的 INSERT 权限的用户
## 语法
```
ALTER TABLE target_table_name APPEND FROM [ source_table_name | source_materialized_view_name ]
[ IGNOREEXTRA | FILLTARGET ]
```
从实体化视图进行追加仅在实体化视图配置为[流式摄取到实体化视图](materialized-view-streaming-ingestion.md)的情形下才有效。
## 参数
*target\$1table\$1name*
要将行附加到的表的名称。只指定表的名称，或者通过格式 *schema\$1name.table\$1name* 使用特定 schema。目标表必须是现有的永久表。
FROM *source\$1table\$1name*
提供要附加的行的表的名称。只指定表的名称，或者通过格式 *schema\$1name.table\$1name* 使用特定 schema。源表必须是现有的永久表。
FROM *source\$1materialized\$1view\$1name*
提供要附加的行的实体化视图的名称。从实体化视图进行追加仅在实体化视图配置为[流式摄取到实体化视图](materialized-view-streaming-ingestion.md)的情形下才有效。源实体化视图必须已经存在。
IGNOREEXTRA
这个关键字指定，如果源表中包含目标表中不存在的列，则应该放弃额外列中的数据。您不能将 IGNOREEXTRA 与 FILLTARGET 配合使用。
FILLTARGET
这个关键字指定，如果目标表中包含源表中不存在的列，则应该使用 [DEFAULT](r_CREATE_TABLE_NEW.md#create-table-default) 列值（如果已定义列值；否则使用 NULL 值）填充这些列。您不能将 IGNOREEXTRA 与 FILLTARGET 配合使用。
## ALTER TABLE APPEND 使用说明
+ ALTER TABLE APPEND 仅将相同列从源表移到目标表。列的顺序不重要。
+ 如果源表或目标表包含额外的列，则根据以下规则使用 FILLTARGET 或 IGNOREEXTRA：
+ 如果源表包含目标表中不存在的列，则包含 IGNOREEXTRA。该命令会忽略源表中额外的列。
+ 如果目标表包含源表中不存在的列，则包含 FILLTARGET。该命令使用默认列值或 IDENTITY 值（如果已定义列值；否则使用 NULL 值）填充目标表中的额外列。
+ 如果源表和目标表均包含额外的列，则该命令失败。您不能同时使用 FILLTARGET 和 IGNOREEXTRA。
+ 如果两个表中的某个列具有相同名称，但具有不同的属性，则该命令失败。名称类似的列必须具有以下共同的属性：
+ 数据类型
+ 列大小
+ 压缩编码
+ 非 Null
+ 排序方式
+ 排序键列
+ 分配方式
+ 分配键列
+ 您不能附加身份列。如果源表和目标表中均具有身份列，则该命令失败。如果只有源表具有身份列，则包含 IGNOREEXTRA 参数以忽略身份列。如果只有目标表具有身份列，则包含 FILLTARGET 参数，以便根据为该表定义的 IDENTITY 子句来填充身份列。有关更多信息，请参阅 [DEFAULT](r_CREATE_TABLE_NEW.md#create-table-default)。
+ 您可以使用 ALTER TABLE APPEND 语句附加默认身份列。有关更多信息，请参阅 [CREATE TABLE](r_CREATE_TABLE_NEW.md)。
+ ALTER TABLE APPEND 操作在连接到以下任何一项的 Amazon Redshift 流式传输实体化视图上运行时，将持有排他锁：
+ Amazon Kinesis 数据流
+ Amazon Managed Streaming for Apache Kafka 主题
+ 支持的外部流，例如 Confluent Cloud Kafka 主题
有关更多信息，请参阅 [流式摄取到实体化视图](materialized-view-streaming-ingestion.md)。
## ALTER TABLE APPEND 示例
假设您的组织维护表 SALES\$1MONTHLY 来获取当前销售交易。您希望每个月将数据从交易表移动到 SALES 表。
您可以使用下面的 INSERT INTO 和 TRUNCATE 命令来完成任务。
```
insert into sales (select * from sales_monthly);
truncate sales_monthly;
```
不过，您可以使用 ALTER TABLE APPEND 命令执行相同的操作，而且效率要高得多。
首先，查询 [PG\$1TABLE\$1DEF](r_PG_TABLE_DEF.md) 系统目录表，验证两个表中包含具有相同列属性的相同列。
```
select trim(tablename) as table, "column", trim(type) as type,
encoding, distkey, sortkey, "notnull"
from pg_table_def where tablename like 'sales%';
table | column | type | encoding | distkey | sortkey | notnull
-----------+------------+-----------------------------+----------+---------+---------+--------
sales | salesid | integer | lzo | false | 0 | true
sales | listid | integer | none | true | 1 | true
sales | sellerid | integer | none | false | 2 | true
sales | buyerid | integer | lzo | false | 0 | true
sales | eventid | integer | mostly16 | false | 0 | true
sales | dateid | smallint | lzo | false | 0 | true
sales | qtysold | smallint | mostly8 | false | 0 | true
sales | pricepaid | numeric(8,2) | delta32k | false | 0 | false
sales | commission | numeric(8,2) | delta32k | false | 0 | false
sales | saletime | timestamp without time zone | lzo | false | 0 | false
salesmonth | salesid | integer | lzo | false | 0 | true
salesmonth | listid | integer | none | true | 1 | true
salesmonth | sellerid | integer | none | false | 2 | true
salesmonth | buyerid | integer | lzo | false | 0 | true
salesmonth | eventid | integer | mostly16 | false | 0 | true
salesmonth | dateid | smallint | lzo | false | 0 | true
salesmonth | qtysold | smallint | mostly8 | false | 0 | true
salesmonth | pricepaid | numeric(8,2) | delta32k | false | 0 | false
salesmonth | commission | numeric(8,2) | delta32k | false | 0 | false
salesmonth | saletime | timestamp without time zone | lzo | false | 0 | false
```
接下来，查看每个表的大小。
```
select count(*) from sales_monthly;
count
-------
2000
(1 row)
select count(*) from sales;
count
-------
412,214
(1 row)
```
现在运行以下 ALTER TABLE APPEND 命令。
```
alter table sales append from sales_monthly;
```
再次查看每个表的大小。SALES\$1MONTHLY 表现在包含 0 行；而 SALES 表增长了 2000 行。
```
select count(*) from sales_monthly;
count
-------
0
(1 row)
select count(*) from sales;
count
-------
414214
(1 row)
```
如果源表中的列多于目标表，请指定 IGNOREEXTRA 参数。以下示例使用 IGNOREEXTRA 参数，这样在附加到 SALES 表时，会忽略 SALES\$1LISTING 表中的额外列。
```
alter table sales append from sales_listing ignoreextra;
```
如果目标表中的列多于源表，请指定 FILLTARGET 参数。以下示例使用 FILLTARGET 参数，以填充 SALES\$1REPORT 表中存在而 SALES\$1MONTH 表中不存在的列。
```
alter table sales_report append from sales_month filltarget;
```
以下示例显示了在实体化视图作为源的情况下如何使用 ALTER TABLE APPEND 的示例。
```
ALTER TABLE target_tbl APPEND FROM my_streaming_materialized_view;
```
此示例中的表和实体化视图名称是示例。从实体化视图进行追加仅在实体化视图配置为[流式摄取到实体化视图](materialized-view-streaming-ingestion.md)的情形下才有效。它将源实体化视图中的所有记录移动到与实体化视图具有相同架构的目标表中，并保持实体化视图不变。这与数据来源为表时的行为相同。
# ALTER TEMPLATE
更改现有模板的定义。使用此命令可重命名模板、更改模板的所有者、在模板定义中添加或移除参数，或设置参数值。
## 所需的权限
要更改模板，您必须拥有以下其中一项：
+ 超级用户权限
+ 对包含模板的架构的 ALTER TEMPLATE 权限和 USAGE 权限
## 语法
```
ALTER TEMPLATE [database_name.][schema_name.]template_name
{
RENAME TO new_name
| OWNER TO new_owner
| ADD parameter [AS] [value]
| DROP parameter
| SET parameter TO value1 [, parameter2 TO value2 , ...]
};
```
## 参数
*database\$1name*
（可选）在其中创建模板的数据库的名称。如果未指定，则使用当前数据库。
*schema\$1name*
（可选）在其中创建模板的架构的名称。如果未指定，则在当前搜索路径中搜索模板。
*template\$1name*
要更改的模板的名称。
RENAME TO
用于重命名模板的子句。
*new\$1name*
模板的新名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
OWNER TO
用于更改模板所有者的子句。
*new\$1owner*
模板的新所有者。
ADD *parameter* [AS] [*value*]
将新参数添加到模板。
+ 对于仅限关键字的参数（例如 CSV 或 GZIP），请仅指定参数名称。
+ 对于需要值的参数，请指定参数名称，且后跟值。您可以选择在参数和值之间包含 AS。
DROP *parameter*
从模板中移除指定的参数。无法使用单个 DROP 命令删除多个参数。
SET *parameter* TO *value1* [, *parameter2* TO *value2* , ...]
更新现有模板参数的值。仅用于已具有值的参数。可以在单个命令中更新多个参数。
## 示例
以下示例将 test\$1template 模板重命名为 demo\$1template。
```
ALTER TEMPLATE test_template
RENAME TO demo_template;
```
以下示例将 demo\$1template 架构的所有权授予用户 bob。
```
ALTER TEMPLATE demo_template
OWNER TO bob;
```
以下示例向模板 demo\$1template 添加参数 `CSV`
```
ALTER TEMPLATE demo_template
ADD CSV;
```
以下示例向模板 demo\$1template 添加参数 `TIMEFORMAT 'auto'`
```
ALTER TEMPLATE demo_template
ADD TIMEFORMAT 'auto';
```
以下示例从模板 demo\$1template 中删除参数 `ENCRYPTED`
```
ALTER TEMPLATE demo_template
DROP ENCRYPTED;
```
以下示例将 `DELIMITER` 参数设置为 `'|'`，并将 `TIMEFORMAT` 参数设置为 `'epochsecs'`：
```
ALTER TEMPLATE demo_template
SET DELIMITER TO '|', TIMEFORMAT TO 'epochsecs';
```
# ALTER USER
更改数据库用户。
## 所需的权限
以下是 ALTER USER 所需的权限：
+ Superuser
+ 具有 ALTER USER 权限的用户
+ 想更改自己密码的当前用户
## 语法
```
ALTER USER username [ WITH ] option [, ... ]
where option is
CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
| SYSLOG ACCESS { RESTRICTED | UNRESTRICTED }
| PASSWORD { 'password' | 'md5hash' | 'sha256hash' | DISABLE }
[ VALID UNTIL 'expiration_date' ]
| RENAME TO new_name |
| CONNECTION LIMIT { limit | UNLIMITED }
| SESSION TIMEOUT limit | RESET SESSION TIMEOUT
| SET parameter { TO | = } { value | DEFAULT }
| RESET parameter
| EXTERNALID external_id
```
## 参数
*username*
用户的名称。
WITH
可选关键字。
CREATEDB \$1 NOCREATEDB
CREATEDB 选项允许用户创建新数据库。NOCREATEDB 是默认值。
CREATEUSER \$1 NOCREATEUSER
使用 CREATEUSER 选项可以创建具备所有数据库权限的超级用户，包括 CREATE USER。默认值为 NOCREATEUSER。有关更多信息，请参阅 [超级用户](r_superusers.md)。
SYSLOG ACCESS \$1 RESTRICTED \$1 UNRESTRICTED \$1
一个子句，它指定用户必须对 Amazon Redshift 系统表和视图具有的访问级别。
拥有 SYSLOG ACCESS RESTRICTED 权限的普通用户在用户可见的系统表和视图中只能查看该用户生成的行。默认值为 RESTRICTED。
拥有 SYSLOG ACCESS UNRESTRICTED 权限的普通用户可以查看用户可见的系统表和视图中的所有行，包括其他用户生成的行。UNRESTRICTED 不向普通用户授予对超级用户可见的表的访问权限。只有超级用户可以查看超级用户可见的表。
如果向用户授予对系统表的无限制访问权限，用户便可以看到由其他用户生成的数据。例如，STL\$1QUERY 和 STL\$1QUERYTEXT 包含 INSERT、UPDATE 和 DELETE 语句的完整文本（其中可能包含敏感的用户生成数据）。
SVV\$1TRANSACTIONS 中的所有行都对所有用户可见。
有关更多信息，请参阅 [系统表和视图中的数据可见性](cm_chap_system-tables.md#c_visibility-of-data)。
PASSWORD \$1 '*password*' \$1 '*md5hash*' \$1 '*sha256hash*' \$1 DISABLE \$1
设置用户的密码。
默认情况下，用户可以更改自己的密码，除非密码被禁用。要禁用用户的密码，请指定 DISABLE。禁用某个用户的密码后，将从系统中删除该密码，而此用户只能使用临时 AWS Identity and Access Management (IAM) 用户凭证进行登录。有关更多信息，请参阅[使用 IAM 身份验证生成数据库用户凭证](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-user-credentials.html)。只有超级用户才能启用或禁用密码。您不能禁用超级用户的密码。要启用密码，请运行 ALTER USER 并指定密码。
有关使用 PASSWORD 参数的详细信息，请参阅[CREATE USER](r_CREATE_USER.md)。
VALID UNTIL '*expiration\$1date*'
指定密码具有过期日期。使用值 `'infinity'` 可避免密码具有过期日期。此参数的有效数据类型为时间戳。
只有超级用户才能使用此参数。
RENAME TO
重命名用户。
*new\$1name*
用户的新名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
在重命名用户时，还必须重置用户的密码。重置密码不必与之前的密码不同。用户名用作密码加密的一部分，因此在重命名用户时，将会清除密码。用户将无法登录，直至重置密码。例如：
```
alter user newuser password 'EXAMPLENewPassword11';
```
CONNECTION LIMIT \$1 *limit* \$1 UNLIMITED \$1
允许用户同时打开的数据库连接的最大数量。此限制不适用于超级用户。使用 UNLIMITED 关键字设置允许的并行连接的最大数量。对每个数据库的连接数量可能也会施加限制。有关更多信息，请参阅 [CREATE DATABASE](r_CREATE_DATABASE.md)。默认为 UNLIMITED。要查看当前连接，请查询 [STV\$1SESSIONS](r_STV_SESSIONS.md) 系统视图。
如果用户及数据库连接限制均适用，当用户尝试连接时，必须有一个同时低于这两个限制的未使用的连接槽可用。
SESSION TIMEOUT *limit* \$1 RESET SESSION TIMEOUT
会话保持非活动或空闲状态的最长时间（秒）。范围在 60 秒（1 分钟）到 1,728,000 秒（20 天）之间。如果没有为用户设置会话超时，则应用集群设置。有关更多信息，请参阅《Amazon Redshift 管理指南》**中的 [Amazon Redshift 中的配额和限制](https://docs.aws.amazon.com/redshift/latest/mgmt/amazon-redshift-limits.html)。
设置会话超时时，它仅应用于新会话。
要查看有关活动用户会话的信息，包括开始时间、用户名和会话超时，请查询 [STV\$1SESSIONS](r_STV_SESSIONS.md) 系统视图。要查看有关用户会话历史记录的信息，请查询 [STL\$1SESSIONS](r_STL_SESSIONS.md) 视图。要检索有关数据库用户的信息（包括会话超时值），请查询 [SVL\$1USER\$1INFO](r_SVL_USER_INFO.md) 视图。
SET
针对指定用户运行的所有会话，将某个配置参数设置为新的默认值。
RESET
为指定用户将某个配置参数重置为原始默认值。
*参数*
要设置或重置的参数的名称。
*值*
参数的新值。
DEFAULT
针对指定用户运行的所有会话，将配置参数设置为默认值。
EXTERNALID *external\$1id*
用户的标识符，与身份提供者关联。用户必须已禁用密码。有关更多信息，请参阅 [Amazon Redshift 的原生身份提供者 (IdP) 联合身份验证](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-native-idp.html)。
## 使用说明
+ **尝试更改 rdsdb** - 您无法更改名为 `rdsdb` 的用户。
+ **创建未知密码** – 使用 AWS Identity and Access Management (IAM) 身份验证创建数据库用户凭证时，您可能希望创建仅使用临时凭证便可以登录的超级用户。您不能禁用超级用户的密码，但可以使用随机生成的 MD5 哈希字符串创建一个未知密码。
```
alter user iam_superuser password 'md51234567890123456780123456789012';
```
+ **设置 search\$1path** – 当您使用 ALTER USER 命令设置 [search\$1path](r_search_path.md) 参数时，所做修改将在指定的用户下次登录时生效。如果您希望更改当前用户和会话的 search\$1path 值，请使用 SET 命令。
+ **设置时区** – 当您将 SET TIMEZONE 与 ALTER USER 命令一起使用时，所做修改将在指定的用户下次登录时生效。
+ **使用动态数据掩蔽和行级安全策略** – 当您的预调配集群或无服务器命名空间具有任何动态数据掩蔽或行级安全策略时，普通用户将无法使用以下命令：
```
ALTER SET enable_case_sensitive_super_attribute/enable_case_sensitive_identifier/downcase_delimited_identifier
```
只有超级用户和具有 ALTER USER 权限的用户才能设置这些配置选项。有关行级别安全性的信息，请参阅[行级别安全性](t_rls.md)。有关动态数据掩蔽的信息，请参阅[动态数据掩蔽](t_ddm.md)。
## 示例
以下示例为用户 ADMIN 授予创建数据库的权限：
```
alter user admin createdb;
```
以下示例将用户 ADMIN 的密码设置为 `adminPass9`，并为密码设置一个到期日期和时间：
```
alter user admin password 'adminPass9'
valid until '2017-12-31 23:59';
```
以下示例将用户 ADMIN 重命名为 SYSADMIN：
```
alter user admin rename to sysadmin;
```
以下示例将用户的空闲会话超时更新为 300 秒。
```
ALTER USER dbuser SESSION TIMEOUT 300;
```
重置用户的空闲会话超时。重置它时，将应用集群设置。您必须是数据库超级用户才能执行此命令。有关更多信息，请参阅《Amazon Redshift 管理指南》**中的 [Amazon Redshift 中的配额和限制](https://docs.aws.amazon.com/redshift/latest/mgmt/amazon-redshift-limits.html)。
```
ALTER USER dbuser RESET SESSION TIMEOUT;
```
以下示例更新名为 `bob` 的用户的外部 ID。命名空间为 `myco_aad`。如果命名空间与注册的身份提供者没有关联，则会导致错误。
```
ALTER USER myco_aad:bob EXTERNALID "ABC123" PASSWORD DISABLE;
```
以下示例为某个特定数据库用户运行的所有会话设置时区。该示例更改后续会话的时区，而不是更改当前会话的时区。
```
ALTER USER odie SET TIMEZONE TO 'Europe/Zurich';
```
以下示例设置了允许用户 `bob` 打开的最大数据库连接数。
```
ALTER USER bob CONNECTION LIMIT 10;
```
# ANALYZE
更新表统计数据以供查询计划程序使用。
## 所需的权限
以下是 ANALYZE 所需的权限：
+ Superuser
+ 具有 ANALYZE 权限的用户
+ 关系的拥有者
+ 向其共享表的数据库拥有者
## 语法
```
ANALYZE [ VERBOSE ]
[ [ table_name [ ( column_name [, ...] ) ] ]
[ PREDICATE COLUMNS | ALL COLUMNS ]
```
## 参数
VERBOSE
返回有关 ANALYZE 操作的进度信息消息的子句。在不指定表时，此选项会非常有用。
*table\$1name*
您可以分析特定表，包括临时表。您可以通过其 schema 名称来限定表。您可以视需要指定 table\$1name 来分析单个表。您不能在单个 *ANALYZE table\$1name* 语句中指定多个 *table\$1name*。如果您不指定 *table\$1name* 值，则将分析当前连接的数据库中的所有表，包括系统目录中的持久性表。如果自上次执行 ANALYZE 以来更改的行数百分比低于分析阈值，Amazon Redshift 将跳过对表的分析。有关更多信息，请参阅 [分析阈值](#r_ANALYZE-threshold)。
您不需要分析 Amazon Redshift 系统表（STL 和 STV 表）。
*column\$1name*
如果您指定 *table\$1name*，您还可以指定表中的一个或多个列（以两旁加括号的逗号分隔列表的形式）。如果指定了列列表，则只分析列出的列。
PREDICATE COLUMNS \$1 ALL COLUMNS
用于指示 ANALYZE 是否应仅包含谓词列的子句。指定 PREDICATE COLUMNS 以仅分析在以前查询中用作谓词的列或可能用作谓词的候选列。指定 ALL COLUMNS 将分析所有列。默认值为 ALL COLUMNS。
如果以下任意一项为 true，则列包括在一组谓词列中。
+ 该列已在查询中用作筛选条件、联接条件或 group by 子句的一部分。
+ 该列为分配键。
+ 该列为排序键的一部分。
如果未将任何列标记为谓词列（例如，由于尚未查询表），则即使指定了 PREDICATE COLUMNS，也仍将分析所有列。发生这种情况时，Amazon Redshift 可能会回复一条消息，例如，对于“*table-name*”找不到谓词列。请分析所有列。有关谓词列的更多信息，请参阅[分析表](t_Analyzing_tables.md)。
## 使用说明
Amazon Redshift 自动对使用以下命令创建的表运行 ANALYZE：
+ CREATE TABLE AS
+ CREATE TEMP TABLE AS
+ SELECT INTO
您无法分析外部表。
在最初创建这些表时，您不需要对这些表运行 ANALYZE 命令。如果修改了这些表，则应通过用来分析其他表的方式来分析这些表。
### 分析阈值
为了减少处理时间并提高整体系统性能，在自上次运行 ANALYZE 命令以来更改的行数百分比低于 [analyze\$1threshold\$1percent](r_analyze_threshold_percent.md) 参数所指定分析阈值的情况下，Amazon Redshift 将跳过对表执行的 ANALYZE 操作。默认情况下，`analyze_threshold_percent` 为 10。要更改当前会话的 `analyze_threshold_percent`，请执行 [SET](r_SET.md) 命令。以下示例将 `analyze_threshold_percent` 更改为 20%。
```
set analyze_threshold_percent to 20;
```
要在仅有少量行发生更改时对表进行分析，请将 `analyze_threshold_percent` 设置为任意较小的数字。例如，如果您将 `analyze_threshold_percent` 设置为 0.01，则在含有 100000000 行的表中至少有 10000 行发生更改时，不会跳过该表。
```
set analyze_threshold_percent to 0.01;
```
如果 ANALYZE 因未达到分析阈值而跳过表，Amazon Redshift 将返回以下消息。
```
ANALYZE SKIP
```
要在即使没有任何行发生更改时仍对所有表进行分析，请将 `analyze_threshold_percent` 设置为 0。
要查看 ANALYZE 操作的结果，请查询 [STL\$1ANALYZE](r_STL_ANALYZE.md) 系统表。
有关分析表的更多信息，请参阅[分析表](t_Analyzing_tables.md)。
## 示例
分析 TICKIT 数据库中的所有表，并返回进度信息。
```
analyze verbose;
```
只分析 LISTING 表。
```
analyze listing;
```
分析 VENUE 表中的 VENUEID 和 VENUENAME 列。
```
analyze venue(venueid, venuename);
```
仅分析 VENUE 表中的谓词列。
```
analyze venue predicate columns;
```
# ANALYZE COMPRESSION
执行压缩分析，并针对所分析的表使用建议的压缩编码生成报告。报告会针对每一列估计与原始编码相比磁盘空间的潜在压缩量。
## 语法
```
ANALYZE COMPRESSION
[ [ table_name ]
[ ( column_name [, ...] ) ] ]
[COMPROWS numrows]
```
## 参数
*table\$1name*
您可以分析特定表的压缩，包括临时表。您可以通过其 schema 名称来限定表。您可以视需要指定 *table\$1name* 来分析单个表。如果您不指定 *table\$1name*，则将分析当前连接的数据库中的所有表。您不能在单个 ANALYZE COMPRESSION 语句中指定多个 *table\$1name*。
*column\$1name*
如果您指定 *table\$1name*，您还可以指定表中的一个或多个列（以两旁加括号的逗号分隔列表的形式）。
COMPROWS
要在压缩分析中用作采样大小的行数。将对来自每个数据切片的行运行分析。例如，如果您指定 COMPROWS 1000000 (1000000)，而系统共包含 4 个切片，则每个切片将读取和分析 250000 行。如果未指定 COMPROWS，则采样大小默认为每个切片 100000 行。如果 COMPROWS 值小于每个切片 100000 行的默认值，则会自动将该值升级到默认值。但是，如果表中的数据量不足，无法得到有意义的样本，则压缩分析将不会生成建议。如果 COMPROWS 数字大于表中的行数，则 ANALYZE COMPRESSION 命令仍会针对所有可用行继续运行压缩分析。如果未指定表，则使用 COMPROWS 会导致错误。
*numrows*
要在压缩分析中用作采样大小的行数。*numrows* 的可接受范围为 1000 到 1000000000 (1,000,000,000) 之间的数字。
## 使用说明
ANALYZE COMPRESSION 获取独占的表锁定，从而阻止对表的并发读写。只在表空闲时运行 ANALYZE COMPRESSION 命令。
运行 ANALYZE COMPRESSION 以根据表内容的采样来获取列编码方案的建议。ANALYZE COMPRESSION 是一个建议工具，不会修改表的列编码。可以通过重新创建表或使用相同 schema 创建新表来应用推荐的编码。使用适当的编码方案重新创建未压缩的表可以显著降低其磁盘上的大小。此方法可节省磁盘空间并改善 I/O 密集型工作负载的查询性能。
ANALYZE COMPRESSION 会跳过实际分析阶段，并直接返回指定为 SORTKEY 的任何列上的原始编码类型。之所以会执行此操作，是因为当 SORTKEY 列的压缩率远高于其他列时，范围受限扫描的执行效果可能会很差。
## 示例
以下示例说明了仅 LISTING 表中列的编码和预计减少的百分比：
```
analyze compression listing;
Table | Column | Encoding | Est_reduction_pct
---------+----------------+----------+-------------------
listing | listid | az64 | 40.96
listing | sellerid | az64 | 46.92
listing | eventid | az64 | 53.37
listing | dateid | raw | 0.00
listing | numtickets | az64 | 65.66
listing | priceperticket | az64 | 72.94
listing | totalprice | az64 | 68.05
listing | listtime | az64 | 49.74
```
以下示例分析了 SALES 表中的 QTYSOLD、COMMISSION 和 SALETIME 列。
```
analyze compression sales(qtysold, commission, saletime);
Table | Column | Encoding | Est_reduction_pct
-------+------------+----------+-------------------
sales | salesid | N/A | 0.00
sales | listid | N/A | 0.00
sales | sellerid | N/A | 0.00
sales | buyerid | N/A | 0.00
sales | eventid | N/A | 0.00
sales | dateid | N/A | 0.00
sales | qtysold | az64 | 83.06
sales | pricepaid | N/A | 0.00
sales | commission | az64 | 71.85
sales | saletime | az64 | 49.63
```
# ATTACH MASKING POLICY
将现有动态数据掩蔽策略附加到列。有关动态数据掩蔽的更多信息，请参阅 [动态数据掩蔽](t_ddm.md)。
超级用户和具有 sys:secadmin 角色的用户或角色可以附加屏蔽策略。
## 语法
```
ATTACH MASKING POLICY
{
policy_name ON relation_name
| database_name.policy_name ON database_name.schema_name.relation_name
}
( { output_column_names | output_path } )
[ USING ( { input_column_names | input_path } ) ]
TO { user_name | ROLE role_name | PUBLIC }
[ PRIORITY priority ];
```
## 参数
*policy\$1name*
要附加的屏蔽策略的名称。
database\$1name
在其中创建策略和关系的数据库的名称。策略和关系必须在同一个数据库中。该数据库可以是连接的数据库，也可以是支持 Amazon Redshift 联合身份验证权限的数据库。
schema\$1name
关系所属的架构的名称。
*relation\$1name*
要将掩蔽策略附加到的关系的名称。
*output\$1column\$1names*
将要应用屏蔽策略的列的名称。
*output\$1paths*
掩蔽策略将应用于的 SUPER 对象的完整路径，包括列名。例如，对于具有名为 `person` 的 SUPER 类型列的关系，*output\$1path* 可能为 `person.name.first_name`。
*input\$1column\$1names*
将用作屏蔽策略输入的列的名称。此参数为可选的。如果未指定，则掩蔽策略使用 *output\$1column\$1names* 作为输入。
*input\$1paths*
将用作掩蔽策略输入的 SUPER 对象的完整路径。此参数为可选的。如果未指定，则掩蔽策略使用 *output\$1path* 作为输入。
*user\$1name*
要附加屏蔽策略的用户的名称。您不能将两个策略附加到用户和列或角色和列的相同组合。您可以将一个策略附加到用户，将另一个策略附加到该用户的角色。在这种情况下，优先级较高的策略适用。
在单个 ATTACH MASKING POLICY 命令中，您只能设置 user\$1name、role\$1name 和 PUBLIC 中的一项。
*role\$1name*
要附加屏蔽策略的角色的名称。您不能将两个策略附加到同一个列/角色对。您可以将一个策略附加到用户，将另一个策略附加到该用户的角色。在这种情况下，优先级较高的策略适用。
在单个 ATTACH MASKING POLICY 命令中，您只能设置 user\$1name、role\$1name 和 PUBLIC 中的一项。
*PUBLIC*
将屏蔽策略附加到访问表的所有用户。您必须为附加到特定列/用户或列/角色对的其他屏蔽策略分配比 PUBLIC 策略更高的优先级，这样才能让这些策略适用。
在单个 ATTACH MASKING POLICY 命令中，您只能设置 user\$1name、role\$1name 和 PUBLIC 中的一项。
*priority*
屏蔽策略的优先级。当多个屏蔽策略应用于给定用户的查询时，具有最高优先级的策略适用。
不能将两个不同的策略以相同的优先级附加到同一列上，即使这两个策略附加到了不同的用户或角色。您可以多次将相同的策略附加到同一组表、输出列、输入列和优先级参数，只要每次附加策略的用户或角色不同即可。
即使两个策略适用于不同的角色，您也无法将一个策略应用于与该列中附加的另一个策略具有相同优先级的列。该字段是可选的。如果未指定优先级，则屏蔽策略默认为优先级为 0。
有关在 Amazon Redshift 联合身份验证权限目录上使用 ATTACH MASKING POLICY 的信息，请参阅[使用 Amazon Redshift 联合身份验证权限管理访问控制](https://docs.aws.amazon.com/redshift/latest/dg/federated-permissions-managing-access.html)。
# ATTACH RLS POLICY
将表上的行级别安全性策略附加到一个或多个用户或角色。
超级用户和具有 `sys:secadmin` 角色的用户或角色可以附加策略。
## 语法
```
ATTACH RLS POLICY
{
policy_name ON [TABLE] table_name [, ...]
| database_name.policy_name ON [TABLE] database_name.schema_name.table_name [, ...]
}
TO { user_name | ROLE role_name | PUBLIC } [, ...]
```
## 参数
*policy\$1name*
策略的名称。
database\$1name
在其中创建策略和关系的数据库的名称。策略和关系必须在同一个数据库中。该数据库可以是连接的数据库，也可以是支持 Amazon Redshift 联合身份验证权限的数据库。
schema\$1name
关系所属的架构的名称。
table\$1name
行级安全策略所附加到的关系。
TO \$1 *user\$1name* \$1 ROLE *role\$1name* \$1 PUBLIC\$1 [, ...]
指定是否将策略附加到一个或多个指定用户或角色。
有关在 Amazon Redshift 联合身份验证权限目录上使用 ATTACH RLS POLICY 的信息，请参阅[使用 Amazon Redshift 联合身份验证权限管理访问控制](https://docs.aws.amazon.com/redshift/latest/dg/federated-permissions-managing-access.html)。
## 使用说明
在使用 ATTACH RLS POLICY 语句时，请遵守以下规则：
+ 附加的表应该包含策略创建语句的 WITH 子句中列出的所有列。
+ Amazon Redshift RLS 支持将 RLS 策略附加到以下对象：
+ 表
+ 视图
+ 后期绑定视图
+ 实体化视图
+ Amazon Redshift RLS 不支持将 RLS 策略附加到以下对象：
+ 目录表
+ 跨数据库关系
+ 外部表
+ 临时表
+ 策略查找表
+ 实体化视图基表
+ 附加到超级用户或具有 `sys:secadmin` 权限的用户的 RLS 策略将被忽略。
## 示例
以下示例将 RLS 策略附加到指定的表和角色组合。当角色为 `analyst` 或 `dbadmin` 的任何用户访问 tickit\$1category\$1redshift 表时，RLS 策略适用于此类用户。
```
ATTACH RLS POLICY policy_concerts ON tickit_category_redshift TO ROLE analyst, ROLE dbadmin;
```
# BEGIN
开始事务。与 START TRANSACTION 同义。
事务是单一的逻辑工作单元，而无论是包含一个命令还是多个命令。一般来说，事务中的所有命令都是在数据库的快照上执行，其开始时间由为 `transaction_snapshot_begin` 系统配置参数设置的值决定。
预设情况下，单独的 Amazon Redshift 操作（查询、DDL 语句、加载）自动提交到数据库。如果要暂停操作提交直到后续工作完成，您需要使用 BEGIN 语句打开一个事务，然后运行所需的命令，最后使用 [COMMIT](r_COMMIT.md) 或 [END](r_END.md) 语句关闭事务。如果需要，您可以使用 [ROLLBACK](r_ROLLBACK.md) 语句停止正在进行的事务。此行为的一个例外是 [TRUNCATE](r_TRUNCATE.md) 命令，它在所运行的事务中提交事务，并且无法回滚。
## 语法
```
BEGIN [ WORK | TRANSACTION ] [ ISOLATION LEVEL option ] [ READ WRITE | READ ONLY ]
START TRANSACTION [ ISOLATION LEVEL option ] [ READ WRITE | READ ONLY ]
Where option is
SERIALIZABLE
| READ UNCOMMITTED
| READ COMMITTED
| REPEATABLE READ
Note: READ UNCOMMITTED, READ COMMITTED, and REPEATABLE READ have no
operational impact and map to SERIALIZABLE in Amazon Redshift. You can see database isolation levels on your cluster
by querying the stv_db_isolation_level table.
```
## 参数
WORK
可选关键字。
TRANSACTION
可选关键字；WORK 和 TRANSACTION 同义。
ISOLATION LEVEL SERIALIZABLE
默认情况下支持可序列化隔离，因此无论此语法是否包含在语句中，事务的行为都是相同的。有关更多信息，请参阅 [管理并发写入操作](c_Concurrent_writes.md)。不支持任何其他隔离级别。
SQL 标准定义了四个事务隔离级别，可防止*脏读*（事务读取并发未提交事务写入的数据）、*不可重复读*（事务重新读取之前已读取的数据，并发现自初始读取以后，另一个已提交的事务已更改了该数据）以及*幻读*（事务重新运行查询，返回满足一组搜索条件的行，然后发现这组行由于另一个最近提交的事务而发生了更改）：
+ 读取未提交：脏读、不可重复读以及幻读是可能的。
+ 读取已提交：不可重复读和幻读是可能的。
+ 可重复读：幻读是可能的。
+ 可序列化：阻止脏读、不可重复读以及幻读。
虽然您可以使用这四个事务隔离级别中的任意一个，不过 Amazon Redshift 会将所有隔离级别作为可序列化级别处理。
READ WRITE
向事务提供读取和写入权限。
READ ONLY
向事务提供只读权限。
## 示例
以下示例开始一个可序列化事务块：
```
begin;
```
以下示例开始一个具有可序列化隔离级别和读写权限的事务块：
```
begin read write;
```
# CALL
运行存储过程。CALL 命令必须包括过程名称和输入参数值。您必须使用 CALL 语句调用存储过程。
**注意**
CALL 不能成为任何常规查询的一部分。
## 语法
```
CALL sp_name ( [ argument ] [, ...] )
```
## 参数
*sp\$1name*
要运行的过程的名称。
*argument*
输入参数的值。此参数也可以是函数名称，例如 `pg_last_query_id()`。您不能将查询用作 CALL 参数。
## 使用说明
Amazon Redshift 存储过程支持嵌套和递归调用，如下所述。此外，请确保您的驱动程序支持是最新的，如下所述
**Topics**
+ [嵌套调用](#r_CALL_procedure-nested-calls)
+ [驱动程序支持](#r_CALL_procedure-driver-support)
### 嵌套调用
Amazon Redshift 存储过程支持嵌套和递归调用。允许的最大嵌套级别数为 16。嵌套调用可以将业务逻辑封装到较小的过程中，这些过程可以由多个调用者共享。
如果调用了具有输出参数的嵌套过程，则该内部过程必须定义 INOUT 参数。在这种情况下，在非常量变量中传递该内部过程。不允许使用 OUT 参数。出现此问题的原因是需要一个变量来保存内部调用的输出。
内部过程和外部过程之间的关系记录在 `from_sp_call` 的 [SVL\$1STORED\$1PROC\$1CALL](r_SVL_STORED_PROC_CALL.md) 列中。
以下示例演示通过 INOUT 参数将变量传递给嵌套过程调用。
```
CREATE OR REPLACE PROCEDURE inner_proc(INOUT a int, b int, INOUT c int) LANGUAGE plpgsql
AS $$
BEGIN
a := b * a;
c := b * c;
END;
$$;
CREATE OR REPLACE PROCEDURE outer_proc(multiplier int) LANGUAGE plpgsql
AS $$
DECLARE
x int := 3;
y int := 4;
BEGIN
DROP TABLE IF EXISTS test_tbl;
CREATE TEMP TABLE test_tbl(a int, b varchar(256));
CALL inner_proc(x, multiplier, y);
insert into test_tbl values (x, y::varchar);
END;
$$;
CALL outer_proc(5);
SELECT * from test_tbl;
a | b
----+----
15 | 20
(1 row)
```
### 驱动程序支持
我们建议您将 Java 数据库连接 (JDBC) 和开放式数据库连接 (ODBC) 驱动程序升级到支持 Amazon Redshift 存储过程的最新版本。
如果客户端工具使用通过 CALL 语句传递给服务器的驱动程序 API 操作，则您可以使用现有驱动程序。输出参数（如果有）将作为包含一行的结果集返回。
最新版本的 Amazon Redshift JDBC 和 ODBC 驱动程序对存储过程发现提供元数据支持。这些最新版本对于自定义 Java 应用程序还支持 `CallableStatement`。有关驱动程序的更多信息，请参阅《Amazon Redshift 管理指南》**中的[使用 SQL 客户端工具连接到 Amazon Redshift 集群](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-to-cluster.html)。
以下示例说明如何对存储过程调用使用 JDBC 驱动程序的不同 API 操作。
```
void statement_example(Connection conn) throws SQLException {
statement.execute("CALL sp_statement_example(1)");
}
void prepared_statement_example(Connection conn) throws SQLException {
String sql = "CALL sp_prepared_statement_example(42, 84)";
PreparedStatement pstmt = conn.prepareStatement(sql);
pstmt.execute();
}
void callable_statement_example(Connection conn) throws SQLException {
CallableStatement cstmt = conn.prepareCall("CALL sp_create_out_in(?,?)");
cstmt.registerOutParameter(1, java.sql.Types.INTEGER);
cstmt.setInt(2, 42);
cstmt.executeQuery();
Integer out_value = cstmt.getInt(1);
}
```
## 示例
以下示例调用过程名称 `test_spl`。
```
call test_sp1(3,'book');
INFO: Table "tmp_tbl" does not exist and will be skipped
INFO: min_val = 3, f2 = book
```
以下示例调用过程名称 `test_spl2`。
```
call test_sp2(2,'2019');
f2 | column2
---------------------+---------
2019+2019+2019+2019 | 2
(1 row)
```
# CANCEL
取消当前正在运行的数据库查询。
CANCEL 命令需要正在运行的查询的进程 ID 或会话 ID，并显示一条确认消息来验证查询已取消。
## 所需的权限
以下是 CANCEL 所需的权限：
+ 取消自己的查询的超级用户
+ 取消用户的查询的超级用户
+ 取消用户的查询并且具有 CANCEL 权限的用户
+ 取消自己的查询的用户
## 语法
```
CANCEL process_id [ 'message' ]
```
## 参数
*process\$1id*
要取消在 Amazon Redshift 集群中运行的查询，请使用 [STV\$1RECENTS](r_STV_RECENTS.md) 中与要取消的查询对应的 `pid`（进程 ID）。
要取消在 Amazon Redshift Serverless 工作组中运行的查询，请使用 [SYS\$1QUERY\$1HISTORY](SYS_QUERY_HISTORY.md) 中与要取消的查询对应的 `session_id`。
'*消息*'
一条可选的确认消息，该消息在查询取消操作完成时显示。如果您不指定消息，Amazon Redshift 将显示默认的确认消息。您必须将消息放在单引号内。
## 使用说明
您不能通过指定*查询 ID* 来取消查询；您必须指定查询的*进程 ID*（PID）或*会话 ID*。您只能取消当前由您的用户运行的查询。超级用户可以取消所有查询。
如果多个会话中的查询在同一个表上保留锁定，则可以使用 [PG\$1TERMINATE\$1BACKEND](PG_TERMINATE_BACKEND.md) 函数终止其中一个会话。进行此操作会强制使已终止会话中的任意当前正在运行的查询释放所有死锁并回滚事务。查询 [STV\$1LOCKS](r_STV_LOCKS.md) 系统表可查看当前保留的锁定。
在特定的内部事件之后，Amazon Redshift 可能会重新启动一个活动会话并分配新的 PID。如果 PID 已发生更改，您可能会收到以下错误消息。
```
Session does not exist. The session PID might have changed. Check the stl_restarted_sessions system table for details.
```
要查找新的 PID，请查询 [STL\$1RESTARTED\$1SESSIONS](r_STL_RESTARTED_SESSIONS.md) 系统表并针对 `oldpid` 列进行筛选。
```
select oldpid, newpid from stl_restarted_sessions where oldpid = 1234;
```
## 示例
要取消 Amazon Redshift 集群中当前正在运行的查询，请先检索要取消的查询的进程 ID。要确定所有当前正在运行的查询的处理 ID，请键入以下命令：
```
select pid, starttime, duration,
trim(user_name) as user,
trim (query) as querytxt
from stv_recents
where status = 'Running';
pid | starttime | duration | user | querytxt
-----+----------------------------+----------+----------+-----------------
802 | 2008-10-14 09:19:03.550885 | 132 | dwuser | select
venuename from venue where venuestate='FL', where venuecity not in
('Miami' , 'Orlando');
834 | 2008-10-14 08:33:49.473585 | 1250414 | dwuser | select *
from listing;
964 | 2008-10-14 08:30:43.290527 | 326179 | dwuser | select
sellerid from sales where qtysold in (8, 10);
```
检查查询文本，确定哪个进程 ID (PID) 对应于您要取消的查询。
键入以下命令以使用 PID 802 来取消该查询：
```
cancel 802;
```
运行查询的会话会显示如下消息：
```
ERROR: Query (168) cancelled on user's request
```
其中 `168` 是查询 ID (而不是用于取消查询的进程 ID)。
或者，您可以指定显示一条自定义消息，而不是默认消息。要指定自定义消息，请使用单引号将消息包含在 CANCEL 命令的结尾：
```
cancel 802 'Long-running query';
```
运行查询的会话会显示如下消息：
```
ERROR: Long-running query
```
# CLOSE
（可选）关闭与已打开游标关联的所有空闲资源。[COMMIT](r_COMMIT.md)、[END](r_END.md) 和 [ROLLBACK](r_ROLLBACK.md) 会自动关闭游标，因此不必使用 CLOSE 命令显式关闭游标。
有关更多信息，请参阅[DECLARE](declare.md)、[FETCH](fetch.md)。
## 语法
```
CLOSE cursor
```
## 参数
*cursor*
要关闭的游标的名称。
## CLOSE 示例
以下命令关闭游标并执行提交，这将结束事务：
```
close movie_cursor;
commit;
```
# COMMENT
创建或更改有关数据库对象的注释。
## 语法
```
COMMENT ON
{
TABLE object_name |
COLUMN object_name.column_name |
CONSTRAINT constraint_name ON table_name |
DATABASE object_name |
VIEW object_name
}
IS 'text' | NULL
```
## 参数
*object\$1name*
要添加注释的数据库对象的名称。您可以将注释添加到以下对象：
+ TABLE
+ COLUMN（还接受 *column\$1name*）。
+ CONSTRAINT（还接受 *constraint\$1name* 和 *table\$1name*）。
+ DATABASE
+ VIEW
+ SCHEMA
IS '*text*' \$1 NULL
要为指定对象添加或替换的注释文本。*文本*字符串的数据类型是 TEXT。将注释放在单引号内。将值设置为 NULL 可删除注释文本。
*column\$1name*
要添加注释的列的名称。COLUMN 的参数。跟随在 `object_name` 中指定的表后面。
*constraint\$1name*
要添加注释的约束的名称。CONSTRAINT 的参数。
*table\$1name*
包含约束的表的名称。CONSTRAINT 的参数。
## 使用说明
要添加或更新注释，您必须是超级用户或数据库对象的所有者。
数据库的注释只能应用于当前数据库。如果您尝试对不同的数据库添加注释，则会显示警告消息。对不存在的数据库添加注释时，会显示同一警告。
不支持对外部表、外部列和后期绑定视图的列进行评论。
## 示例
以下示例将注释添加到 SALES 表中。
```
COMMENT ON TABLE sales IS 'This table stores tickets sales data';
```
以下示例在 SALES 表中显示该注释。
```
select obj_description('public.sales'::regclass);
obj_description
-------------------------------------
This table stores tickets sales data
```
以下示例从 SALES 表中删除注释。
```
COMMENT ON TABLE sales IS NULL;
```
以下示例将注释添加到 SALES 表的 EVENTID 列中。
```
COMMENT ON COLUMN sales.eventid IS 'Foreign-key reference to the EVENT table.';
```
以下示例在 SALES 表的 EVENTID 列（列号 5）中显示注释。
```
select col_description( 'public.sales'::regclass, 5::integer );
col_description
-----------------------------------------
Foreign-key reference to the EVENT table.
```
以下示例将描述性注释添加到 EVENT 表。
```
comment on table event is 'Contains listings of individual events.';
```
要查看注释，请查询 PG\$1DESCRIPTION 系统目录。以下示例返回 EVENT 表的描述。
```
select * from pg_catalog.pg_description
where objoid =
(select oid from pg_class where relname = 'event'
and relnamespace =
(select oid from pg_catalog.pg_namespace where nspname = 'public') );
objoid | classoid | objsubid | description
-------+----------+----------+----------------------------------------
116658 | 1259 | 0 | Contains listings of individual events.
```
# COMMIT
将当前事务提交到数据库。此命令使事务中的数据库更新永久生效。
## 语法
```
COMMIT [ WORK | TRANSACTION ]
```
## 参数
WORK
可选关键字。存储过程中不支持此关键字。
TRANSACTION
可选关键字。WORK 和 TRANSACTION 是同义词。两者在存储过程中均不受支持。
有关在存储过程中使用 COMMIT 的信息，请参阅[管理事务](stored-procedure-transaction-management.md)。
## 示例
下面的每个示例都将当前事务提交到数据库：
```
commit;
```
```
commit work;
```
```
commit transaction;
```
# 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
```
# CREATE DATABASE
创建新数据库。
要创建数据库，您必须是超级用户或拥有 CREATEDB 权限。要创建与零 ETL 集成关联的数据库，您必须是超级用户或同时拥有 CREATEDB 和 CREATEUSER 权限。
您不能在以下事务块中运行 CREATE DATABASE：(BEGIN ... END)。有关事务的更多信息，请参阅 [Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
## 语法
```
CREATE DATABASE database_name
[ { [
FROM INTEGRATION ''[ DATABASE '' ]
[ SET ]
[ ACCEPTINVCHARS [=] { TRUE | FALSE }]
[ QUERY_ALL_STATES [=] { TRUE | FALSE }]
[ REFRESH_INTERVAL ]
[ TRUNCATECOLUMNS [=] { TRUE | FALSE } ]
[ HISTORY_MODE [=] {TRUE | FALSE} ]
]
[ WITH ]
[ OWNER [=] db_owner ]
[ CONNECTION LIMIT { limit | UNLIMITED } ]
[ COLLATE { CASE_SENSITIVE | CS | CASE_INSENSITIVE | CI } ]
[ ISOLATION LEVEL { SNAPSHOT | SERIALIZABLE } ]
}
| { FROM { { ARN '' } { WITH DATA CATALOG SCHEMA '' | WITH NO DATA CATALOG SCHEMA } } }
| { IAM_ROLE {default | 'SESSION' | 'arn:aws:iam:::role/' } }
| { [ WITH PERMISSIONS ] FROM DATASHARE datashare_name OF [ ACCOUNT account_id ] NAMESPACE namespace_guid }
]
```
## 参数
*database\$1name*
新数据库的名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
FROM INTEGRATION '' [ DATABASE '' ]
指定是否使用零 ETL 集成标识符创建数据库。您可以从 SVV\$1INTEGRATION 系统视图中检索 `integration_id`。对于 Aurora PostgreSQL 零 ETL 集成，还需要指定 `source_database` 名称，这也可以从 SVV\$1INTEGRATION 中检索到。
有关示例，请参阅[创建数据库以接收零 ETL 集成的结果](#r_CREATE_DATABASE-integration)。有关使用零 ETL 集成创建数据库的更多信息，请参阅*《Amazon Redshift 管理指南》*中的[在 Amazon Redshift 中创建目标数据库](https://docs.aws.amazon.com/redshift/latest/mgmt/zero-etl-using.creating-db.html)。
SET
可选关键字。
ACCEPTINVCHARS [=] \$1 TRUE \$1 FALSE \$1
ACCEPTINVCHARS 子句设置在检测到 VARCHAR 数据类型的无效字符时，零 ETL 集成表是否继续摄取。在遇到无效字符时，无效字符将被替换为默认 `?` 字符。
QUERY\$1ALL\$1STATES [=] \$1 TRUE \$1 FALSE \$1
QUERY\$1ALL\$1STATES 子句设置是否可以在所有状态（`Synced`、`Failed`、`ResyncRequired` 和 `ResyncInitiated`）下查询零 ETL 集成表。默认情况下，只能在 `Synced` 状态下查询零 ETL 集成表。
REFRESH\$1INTERVAL
REFRESH\$1INTERVAL 子句设置将数据从零 ETL 源刷新到目标数据库的大致时间间隔（秒）。对于源类型为 Aurora MySQL、Aurora PostgreSQL 或 RDS for MySQL 的零 ETL 集成，该值可设置为 0-432000 秒（5 天）。对于 Amazon DynamoDB 零 ETL 集成，值可设置为 900-432000 秒（15 分钟 - 5 天）。对于源类型为 Aurora MySQL、Aurora PostgreSQL 或 RDS for MySQL 的零 ETL 集成，默认 `interval` 为零（0）秒。对于 Amazon DynamoDB 零 ETL 集成，默认 `interval` 为 900 秒（15 分钟）。
TRUNCATECOLUMNS [=] \$1 TRUE \$1 FALSE \$1
TRUNCATECOLUMNS 子句设置当 VARCHAR 列或 SUPER 列属性的值超出限制时，零 ETL 集成表是否继续摄取。当为 `TRUE` 时，值会被截断以适合该列，而溢出的 JSON 属性的值会被截断以适合 SUPER 列。
HISTORY\$1MODE [=] \$1TRUE \$1 FALSE\$1
一个子句，用于指定 Amazon Redshift 是否为指定数据库中的所有新表设置历史记录模式。此选项仅适用于为零 ETL 集成创建的数据库。
HISTORY\$1MODE 子句可设置为 `TRUE` 或 `FALSE`。默认值为 `FALSE`。有关 HISTORY\$1MODE 的信息，请参阅《Amazon Redshift 管理指南》**中的[历史记录模式](https://docs.aws.amazon.com/redshift/latest/mgmt/zero-etl-history-mode.html)。
WITH
可选关键字。
OWNER [=] db\$1owner
指定数据库所有者的用户名。
CONNECTION LIMIT \$1 *limit* \$1 UNLIMITED \$1
允许用户同时打开的数据库连接的最大数量。此限制不适用于超级用户。使用 UNLIMITED 关键字设置允许的并行连接的最大数量。可能对每个用户的连接数量也会施加限制。有关更多信息，请参阅 [CREATE USER](r_CREATE_USER.md)。默认为 UNLIMITED。要查看当前连接，请查询 [STV\$1SESSIONS](r_STV_SESSIONS.md) 系统视图。
如果用户及数据库连接限制均适用，当用户尝试连接时，必须有一个同时低于这两个限制的未使用的连接槽可用。
COLLATE \$1 CASE\$1SENSITIVE \$1 CS \$1 CASE\$1INSENSITIVE \$1 CI \$1
指定字符串搜索或比较是区分大小写还是不区分大小写的子句。默认为区分大小写。
从数据共享创建数据库时，不支持 COLLATE。
CASE\$1SENSITIVE 和 CS 可以互换，生成的结果相同。同样，CASE\$1INSENSITIVE 和 CI 可以互换，生成的结果相同。
ISOLATION LEVEL \$1 SNAPSHOT \$1 SERIALIZABLE \$1
指定针对数据库运行查询时使用的隔离级别的子句。有关隔离级别的更多信息，请参阅[Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
+ SNAPSHOT 隔离 – 提供隔离级别，来防止出现更新和删除冲突。这是在预调配集群或无服务器命名空间中创建的数据库的默认设置。
+ SERIALIZABLE 隔离 – 为并发事务提供完全可序列性。
FROM ARN ''
用于创建数据库的 AWS Glue 数据库 ARN。
\$1 WITH DATA CATALOG SCHEMA '' \$1 WITH NO DATA CATALOG SCHEMA \$1
仅当您的 CREATE DATABASE 命令也使用 FROM ARN 参数时，此参数才适用。
指定是否使用架构创建数据库以帮助访问 AWS Glue Data Catalog 中的对象。
IAM\$1ROLE \$1 default \$1 'SESSION' \$1 'arn:aws:iam::**:role/**' \$1
仅当您的 CREATE DATABASE 命令也使用 FROM ARN 参数时，此参数才适用。
如果您在运行 CREATE DATABASE 命令时指定与集群关联的 IAM 角色，则 Amazon Redshift 将在您对数据库运行查询时使用该角色的凭证。
指定 `default` 关键字表示要使用设置为默认并与集群关联的 IAM 角色。
如果您使用联合身份连接到 Amazon Redshift 集群并访问使用此命令创建的外部架构中的表，则使用 `'SESSION'`。有关使用联合身份的示例，请参阅[使用联合身份管理 Amazon Redshift 对本地资源和 Amazon Redshift Spectrum 外部表的访问权限](https://docs.aws.amazon.com/redshift/latest/mgmt/authorization-fas-spectrum.html)，其中说明了如何配置联合身份。
使用 IAM 角色的 Amazon 资源名称（ARN），您的集群使用该角色进行身份验证和授权。IAM 角色至少必须有权在要访问的 Amazon S3 桶上执行 LIST 操作和有权在该桶包含的 Amazon S3 对象上执行 GET 操作。要了解有关在使用 AWS Glue Data Catalog 为数据共享创建数据库时使用 IAM\$1ROLE 的更多信息，请参阅[以使用者身份使用 Lake Formation 托管的数据共享](https://docs.aws.amazon.com/redshift/latest/dg/lake-formation-getting-started-consumer.html)。
下面显示了单个 ARN 的 IAM\$1ROLE 参数字符串的语法。
```
IAM_ROLE 'arn:aws:iam:::role/'
```
您可以将角色串联起来，以便集群可以承担另一个 IAM 角色 (可能属于其他账户)。您最多可串联 10 个角色。有关更多信息，请参阅 [在 Amazon Redshift Spectrum 中链接 IAM 角色](c-spectrum-iam-policies.md#c-spectrum-chaining-roles)。
对于此 IAM 角色，请附加类似于以下内容的 IAM 权限策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:ListSecretVersionIds"
],
"Resource": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-rds-secret-VNenFy"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"secretsmanager:GetRandomPassword",
"secretsmanager:ListSecrets"
],
"Resource": "*"
}
]
}
```
有关创建 IAM 角色以用于联合查询的步骤，请参阅[创建密钥和 IAM 角色以使用联合查询](federated-create-secret-iam-role.md)。
请不要在链接的角色列表中包含空格。
下面显示了串联三个角色的语法。
```
IAM_ROLE 'arn:aws:iam:::role/,arn:aws:iam:::role/,arn:aws:iam:::role/'
```
## 将 CREATE DATABASE 与数据共享结合使用的语法
以下语法描述了用于从数据共享中创建数据库以在同一 AWS 账户内共享数据的 CREATE DATABASE 命令。
```
CREATE DATABASE database_name
[ [ WITH PERMISSIONS ] FROM DATASHARE datashare_name OF [ ACCOUNT account_id ] NAMESPACE namespace_guid
```
以下语法描述了用于从数据共享中创建数据库以在 AWS 账户间共享数据的 CREATE DATABASE 命令。
```
CREATE DATABASE database_name
[ [ WITH PERMISSIONS ] FROM DATASHARE datashare_name OF ACCOUNT account_id NAMESPACE namespace_guid
```
### 将 CREATE DATABASE 与数据共享结合使用的参数
FROM DATASHARE
指示数据库所在位置的关键词。
*datashare\$1name*
创建使用者数据库所在的数据共享的名称。
WITH PERMISSIONS
指定通过数据共享创建的数据库需要对象级权限才能访问各个数据库对象。如果没有此子句，则被授予对数据库的 USAGE 权限的用户或角色将自动有权访问数据库中的所有数据库对象。
NAMESPACE *namespace\$1guid*
指定数据共享所属的生产者命名空间的值。
ACCOUNT *account\$1id*
指定数据共享所属的生产者账户的值。
## 用于数据共享的 CREATE DATABASE 的使用说明
作为数据库超级用户，当您使用 CREATE DATABASE 从 AWS 账户内的数据共享创建数据库时，指定 NAMESPACE 选项。ACCOUNT 选项为可选项。当您使用 CREATE DATABASE 从 AWS 账户间的数据共享创建数据库时，同时指定生产者的 ACCOUNT 和 NAMESPACE。
对于使用者集群上的数据共享，一个数据共享仅可创建一个使用者数据库。不能创建多个引用同一数据共享的使用者数据库。
## CREATE DATABASE（从 AWS Glue Data Catalog）
要使用 AWS Glue 数据库 ARN 创建数据库，请在 CREATE DATABASE 命令中指定 ARN。
```
CREATE DATABASE sampledb FROM ARN WITH NO DATA CATALOG SCHEMA;
```
或者，您也可以为 IAM\$1ROLE 参数提供一个值。有关参数和接受的值的更多信息，请参阅[参数](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_DATABASE.html#r_CREATE_DATABASE-parameters)。
以下示例演示了如何使用 IAM 角色从 ARN 创建数据库。
```
CREATE DATABASE sampledb FROM ARN WITH NO DATA CATALOG SCHEMA IAM_ROLE
```
```
CREATE DATABASE sampledb FROM ARN WITH NO DATA CATALOG SCHEMA IAM_ROLE default;
```
您也可以使用 DATA CATALOG SCHEMA 创建数据库。
```
CREATE DATABASE sampledb FROM ARN WITH DATA CATALOG SCHEMA IAM_ROLE default;
```
## 创建数据库以接收零 ETL 集成的结果
要使用零 ETL 集成标识创建数据库，请在 CREATE DATABASE 命令中指定 `integration_id`。
```
CREATE DATABASE destination_db_name FROM INTEGRATION 'integration_id';
```
例如，首先从 SVV\$1INTEGRATION 中获取集成 ID；
```
SELECT integration_id FROM SVV_INTEGRATION;
```
然后使用检索到的其中一个集成 ID 创建接收零 ETL 集成的数据库。
```
CREATE DATABASE sampledb FROM INTEGRATION 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111';
```
例如，当需要零 ETL 集成源数据库时，请指定。
```
CREATE DATABASE sampledb FROM INTEGRATION 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' DATABASE sourcedb;
```
您还可以设置数据库的刷新间隔。例如，将来自零 ETL 集成源的数据的刷新间隔设为 7200 秒：
```
CREATE DATABASE myacct_mysql FROM INTEGRATION 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' SET REFRESH_INTERVAL 7200;
```
查询 SVV\$1INTEGRATION 目录视图，以获取零 ETL 集成的相关信息，如 integration\$1id、target\$1database、source、refresh\$1interval 等。
```
SELECT * FROM svv_integration;
```
以下示例从已启用历史记录模式的集成中创建数据库。
```
CREATE DATABASE sample_integration_db FROM INTEGRATION 'a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' SET HISTORY_MODE = true;
```
## CREATE DATABASE 限制
Amazon Redshift 针对数据库强制实施以下限制：
+ 每个集群最多 60 个用户定义的数据库。
+ 数据库名称最多为 127 个字节。
+ 数据库名称不能使用保留字。
## 数据库排序规则
排序规则是一组规则，用于定义数据库引擎如何对 SQL 中的字符类型数据进行比较和排序。不区分大小写的排序规则是最常用的排序规则。Amazon Redshift 使用不区分大小写的排序规则以帮助从其他数据仓库系统迁移。凭借对不区分大小写的排序规则的本机支持，Amazon Redshift 继续使用重要的调整或优化方法，如分配键、排序键或范围限制扫描。
COLLATE 子句指定数据库中所有 CHAR 和 VARCHAR 列的默认排序规则。如果指定了 CASE\$1INSENSITIVE，则所有 CHAR 或 VARCHAR 列都使用不区分大小写的排序规则。有关排序规则的信息，请参阅[排序规则序列](c_collation_sequences.md)。
在不区分大小写的列中插入或摄取的数据将保持其原始大小写。但是所有基于比较的字符串操作，包括排序和分组都不区分大小写。模式匹配操作（如类似于的 LIKE 谓词）和正则表达式函数也不区分大小写。
以下 SQL 操作支持适用的排序规则语义：
+ 比较运算符：=、<>、<、<=、>、>=。
+ LIKE 运算符
+ ORDER BY 子句
+ GROUP BY 子句
+ 使用字符串比较的聚合函数，例如 MIN、MAX 和 LISTAGG
+ 窗口函数，如 PARTITION BY 子句和 ORDER BY 子句
+ 标量函数 greatest() 和 least()、STRPOS()、REGEXP\$1COUNT()、REGEXP\$1REPLACE()、REGEXP\$1INSTR()、REGEXP\$1SUBSTR()
+ Distinct 子句
+ UNION、INTERSECT 和 EXCEPT
+ IN LIST
对于外部查询（包括 Amazon Redshift Spectrum 和 Aurora PostgreSQL 联合查询），VARCHAR 或 CHAR 列的排序规则与当前数据库级别的排序规则相同。
以下示例将查询 Amazon Redshift Spectrum 表：
```
SELECT ci_varchar FROM spectrum.test_collation
WHERE ci_varchar = 'AMAZON';
ci_varchar
----------
amazon
Amazon
AMAZON
AmaZon
(4 rows)
```
有关如何使用数据库排序规则创建表的信息，请参阅[CREATE TABLE](r_CREATE_TABLE_NEW.md)。
有关 COLLATE 函数的信息，请参阅[COLLATE 函数](r_COLLATE.md)。
### 数据库排序规则限制
以下是在 Amazon Redshift 中使用数据库排序规则时的限制：
+ 所有系统表或视图（包括 PG 目录表和 Amazon Redshift 系统表）均区分大小写。
+ 当使用者数据库和生产者数据库具有不同的数据库级排序规则时，Amazon Redshift 不支持跨数据库和跨集群查询。
+ Amazon Redshift 不支持仅领导节点查询中不区分大小写的排序规则。
以下示例显示了一个不受支持的不区分大小写的查询以及 Amazon Redshift 发送的错误：
```
SELECT collate(usename, 'case_insensitive') FROM pg_user;
ERROR: Case insensitive collation is not supported in leader node only query.
```
+ Amazon Redshift 不支持区分大小写和不区分大小写的列之间的交互，例如比较、函数、联接或集合运算。
以下示例显示了区分大小写和不区分大小写的列交互时出现的错误：
```
CREATE TABLE test
(ci_col varchar(10) COLLATE case_insensitive,
cs_col varchar(10) COLLATE case_sensitive,
cint int,
cbigint bigint);
```
```
SELECT ci_col = cs_col FROM test;
ERROR: Query with different collations is not supported yet.
```
```
SELECT concat(ci_col, cs_col) FROM test;
ERROR: Query with different collations is not supported yet.
```
```
SELECT ci_col FROM test UNION SELECT cs_col FROM test;
ERROR: Query with different collations is not supported yet.
```
```
SELECT * FROM test a, test b WHERE a.ci_col = b.cs_col;
ERROR: Query with different collations is not supported yet.
```
```
Select Coalesce(ci_col, cs_col) from test;
ERROR: Query with different collations is not supported yet.
```
```
Select case when cint > 0 then ci_col else cs_col end from test;
ERROR: Query with different collations is not supported yet.
```
要使这些查询起作用，请使用 COLLATE 函数将一个列的排序规则转换为与另一列匹配。有关更多信息，请参阅 [COLLATE 函数](r_COLLATE.md)。
## 示例
**创建数据库**
以下示例创建名为 TICKIT 的数据库并将所有权授予用户 DWUSER。
```
create database tickit
with owner dwuser;
```
要查看有关数据库的详细信息，请查询 PG\$1DATABASE\$1INFO 目录表。
```
select datname, datdba, datconnlimit
from pg_database_info
where datdba > 1;
datname | datdba | datconnlimit
-------------+--------+-------------
admin | 100 | UNLIMITED
reports | 100 | 100
tickit | 100 | 100
```
以下示例使用 SNAPSHOT 隔离级别创建名为 **sampledb** 的数据库。
```
CREATE DATABASE sampledb ISOLATION LEVEL SNAPSHOT;
```
以下示例从数据共享 salesshare 中创建了数据库 sales\$1db。
```
CREATE DATABASE sales_db FROM DATASHARE salesshare OF NAMESPACE '13b8833d-17c6-4f16-8fe4-1a018f5ed00d';
```
### 数据库排序规则示例
**创建不区分大小写的数据库**
以下示例将创建 `sampledb` 数据库、创建 `T1` 表，并将数据插入 `T1` 表中。
```
create database sampledb collate case_insensitive;
```
连接到您刚刚使用 SQL 客户端创建的新数据库。使用 Amazon Redshift 查询编辑器 v2 时，在**编辑器**中选择 `sampledb`。使用 RSQL 时，请使用如下命令。
```
\connect sampledb;
```
```
CREATE TABLE T1 (
col1 Varchar(20) distkey sortkey
);
```
```
INSERT INTO T1 VALUES ('bob'), ('john'), ('Mary'), ('JOHN'), ('Bob');
```
然后，查询查找含有 `John` 的结果。
```
SELECT * FROM T1 WHERE col1 = 'John';
col1
------
john
JOHN
(2 row)
```
**按不区分大小写的顺序排序**
以下示例显示了表 T1 中不区分大小写的排序。*Bob* 与 *bob* 或 *John* 与 *john* 的排序具有不确定性，因为它们在不区分大小写的列中是相等的。
```
SELECT * FROM T1 ORDER BY 1;
col1
------
bob
Bob
JOHN
john
Mary
(5 rows)
```
同样，以下示例显示了 GROUP BY 子句中不区分大小写的排序。*Bob* 和 *bob* 是相等的，并且属于同一个组。结果中显示哪一个是不确定的。
```
SELECT col1, count(*) FROM T1 GROUP BY 1;
col1 | count
-----+------
Mary | 1
bob | 2
JOHN | 2
(3 rows)
```
**使用窗口函数对不区分大小写的列进行查询**
以下示例在不区分大小写的列上查询窗口函数。
```
SELECT col1, rank() over (ORDER BY col1) FROM T1;
col1 | rank
-----+------
bob | 1
Bob | 1
john | 3
JOHN | 3
Mary | 5
(5 rows)
```
**使用 DISTINCT 关键词进行查询**
以下示例查询带有 DISTINCT 关键词的 `T1` 表。
```
SELECT DISTINCT col1 FROM T1;
col1
------
bob
Mary
john
(3 rows)
```
**使用 UNION 子句进行查询**
以下示例显示来自表 `T1` 和 `T2` 的 UNION 的结果。
```
CREATE TABLE T2 AS SELECT * FROM T1;
```
```
SELECT col1 FROM T1 UNION SELECT col1 FROM T2;
col1
------
john
bob
Mary
(3 rows)
```
# CREATE DATASHARE
在当前数据库中创建一个新数据共享。此数据共享的拥有者为 CREATE DATASHARE 命令的发布者。
Amazon Redshift 将每个数据共享与一个 Amazon Redshift 数据库相关联。您只能将关联数据库中的对象添加到数据共享中。您可以在同一个 Amazon Redshift 数据库上创建多个数据共享。
有关数据共享的信息，请参阅[Amazon Redshift 中的数据共享](datashare-overview.md)。
要查看有关数据共享的信息，请使用[SHOW DATASHARES](r_SHOW_DATASHARES.md)。
## 所需的权限
以下是 CREATE DATASHARE 所需的权限：
+ Superuser
+ 具有 CREATE DATASHARE 权限的用户
+ 数据库拥有者
## 语法
```
CREATE DATASHARE datashare_name
[[SET] PUBLICACCESSIBLE [=] TRUE | FALSE ];
```
## 参数
*datashare\$1name*
数据共享的名称。数据共享名称在集群命名空间中必须是唯一的。
[[SET] PUBLICACCESSIBLE]
指定是否可以将数据共享共享给可公开访问的集群的子句。
`SET PUBLICACCESSIBLE` 的默认值为 `FALSE`。
## 使用说明
预设情况下，数据共享的拥有者仅拥有共享，而不拥有共享中的对象。
只有超级用户和数据库拥有者才能使用 CREATE DATASHARE 并将 ALTER 权限委派给其他用户或组。
## 示例
以下示例创建了数据共享 `salesshare`。
```
CREATE DATASHARE salesshare;
```
以下示例创建了 AWS Data Exchange 管理的数据共享 `demoshare`。
```
CREATE DATASHARE demoshare SET PUBLICACCESSIBLE TRUE, MANAGEDBY ADX;
```
# CREATE EXTERNAL FUNCTION
根据 Amazon Redshift 的 AWS Lambda 创建标量用户定义函数 (UDF)。有关 Lambda 用户定义函数的更多信息，请参阅[标量 Lambda UDF](udf-creating-a-lambda-sql-udf.md)。
## 所需的权限
以下是 CREATE EXTERNAL FUNCTION 所需的权限：
+ Superuser
+ 具有 CREATE [ OR REPLACE ] EXTERNAL FUNCTION 权限的用户
## 语法
```
CREATE [ OR REPLACE ] EXTERNAL FUNCTION external_fn_name ( [data_type] [, ...] )
RETURNS data_type
{ VOLATILE | STABLE }
LAMBDA 'lambda_fn_name'
IAM_ROLE { default | ‘arn:aws:iam:::role/’
RETRY_TIMEOUT milliseconds
MAX_BATCH_ROWS count
MAX_BATCH_SIZE size [ KB | MB ];
```
## 参数
OR REPLACE
一个子句，指定如果某个函数与已存在的此函数具有相同的名称和输入参数数据类型或*签名*，则替换现有的函数。您只能将某个函数替换为定义一组相同数据类型的新函数。您必须是超级用户才能替换函数。
如果您定义的函数与现有函数具有相同的名称，但签名不同，则创建新的函数。换而言之，函数名称将会重载。有关更多信息，请参阅 [重载函数名称](udf-naming-udfs.md#udf-naming-overloading-function-names)。
*external\$1fn\$1name*
外部函数的名称。如果您指定 schema 名称（例如 myschema.myfunction），则使用指定的 schema 创建函数。否则，将在当前 schema 中创建该函数。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
我们建议您将所有 UDF 名称添加前缀 `f_`。Amazon Redshift 保留 `f_` 前缀，用于 UDF 名称。通过使用 `f_` 前缀，您可以帮助确保您的 UDF 名称现在或将来不会与 Amazon Redshift 的任何内置 SQL 函数名称发生冲突。有关更多信息，请参阅 [防止 UDF 命名冲突](udf-naming-udfs.md)。
*data\$1type*
输入参数的数据类型。有关更多信息，请参阅[标量 Python UDF](udf-creating-a-scalar-udf.md)和[标量 Lambda UDF](udf-creating-a-lambda-sql-udf.md)。
RETURNS *data\$1type*
函数返回的值的数据类型。RETURNS 数据类型可以是任何标准的 Amazon Redshift 数据类型。有关更多信息，请参阅[标量 Python UDF](udf-creating-a-scalar-udf.md)和[标量 Lambda UDF](udf-creating-a-lambda-sql-udf.md)。
VOLATILE \$1 STABLE
通知查询优化程序有关函数的不稳定性。
要获得最大程度的优化，将函数标记为其有效的最严格稳定性类别。按照严格性顺序，从最不严格的开始，稳定性类别如下所示：
+ VOLATILE
+ STABLE
VOLATILE
对于相同的参数，函数会对连续的调用返回不同的结果，甚至对于单个语句中的行也是如此。查询优化器无法对不稳定函数的行为做出假设。使用不稳定函数的查询必须对每个输入重新计算该函数。
STABLE
对于相同的参数，可保证函数对在单个语句内处理的所有后续调用返回相同的结果。在不同的语句中调用时，函数可能会返回不同的结果。通过这一类别，优化器可以减少在单个语句中调用函数的次数。
请注意，如果所选的严格性对函数无效，则存在优化器可能会基于这种严格性跳过某些调用的风险。这可能会导致结果集不正确。
Lambda UDF 目前不支持 IMMUTABLE 子句。
LAMBDA *'lambda\$1fn\$1name'*
Amazon Redshift 调用的函数的名称。
有关创建 AWS Lambda 函数的步骤，请参阅《AWS Lambda 开发人员指南》**中的[使用控制台创建 Lambda 函数](https://docs.aws.amazon.com/lambda/latest/dg/getting-started-create-function.html)。
有关 Lambda 函数所需权限的信息，请参阅《AWS Lambda 开发人员指南》**中的 [AWS Lambda 权限](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html)。
IAM\$1ROLE \$1 default \$1 ‘arn:aws:iam::**:role/**’
使用默认关键字让 Amazon Redshift 使用 IAM 角色，该角色设置为默认值并在 CREATE EXTERNAL FUNCTION 命令运行时与集群关联。
使用 IAM 角色的 Amazon 资源名称（ARN），您的集群使用该角色进行身份验证和授权。CREATE EXTERNAL FUNCTION 命令被授权通过此 IAM 角色调用 Lambda 函数。如果您的集群具有有权调用所附加 Lambda 函数的现有 IAM 角色，您可以替换您的角色的 ARN。有关更多信息，请参阅 [配置 Lambda UDF 的授权参数](udf-creating-a-lambda-sql-udf.md#udf-lambda-authorization)。
以下显示 IAM\$1ROLE 参数的语法。
```
IAM_ROLE 'arn:aws:iam::aws-account-id:role/role-name'
```
RETRY\$1TIMEOUT *毫秒*
Amazon Redshift 用于重试退避延迟的总时间（以毫秒为单位）。
Amazon Redshift 不会立即重试任何失败的查询，而是执行退避并等待一定时间间隔再重试。然后，Amazon Redshift 将重试请求，以重新运行失败的查询，直到所有延迟的总和等于或超过您指定的 RETRY\$1TIMEOUT 值。默认值为 20000 毫秒。
当调用 Lambda 函数时，Amazon Redshift 会重试接收 `TooManyRequestsException`、`EC2ThrottledException` 和 `ServiceException` 等错误的查询。
您可以将 RETRY\$1TIMEOUT 参数设置为 0 毫秒，以防止对 Lambda UDF 进行任何重试。
MAX\$1BATCH\$1ROWS *count*
Amazon Redshift 在单个批处理请求中为单个 lambda 调用发送的最大行数。
此参数的最小值为 1。最大值为 INT\$1MAX，即 2,147,483,647。
此参数为可选的。默认值为 INT\$1MAX，即 2,147,483,647。
MAX\$1BATCH\$1SIZE *size* [ KB \$1 MB ]
Amazon Redshift 在单个批处理请求中为单个 lambda 调用发送的数据负载的最大大小。
此参数的最小值为 1 KB。最大值为 5 MB。
此参数的默认值为 5 MB。
KB 和 MB 是可选的。如果您未设置计量单位，则 Amazon Redshift 默认使用 KB。
## 使用说明
创建 Lambda UDF 时请考虑以下几点：
+ Lambda 函数调用输入参数的顺序不是固定的或有保证的。这可能因正在运行的查询实例而异，具体取决于集群配置。
+ 不能保证函数对每个输入参数应用一次，且只应用一次。Amazon Redshift 和 AWS Lambda 之间的交互可能会导致使用相同输入的重复调用。
## 示例
以下是使用标量 Lambda 用户定义函数 (UDF) 的示例。
### 使用 Node.js Lambda 函数的标量 Lambda UDF 示例
以下示例创建一个名为 `exfunc_sum` 的外部函数，它将两个整数作为输入参数。此函数以整数输出形式返回总和。要调用的 Lambda 函数的名称为 `lambda_sum`。用于此 Lambda 函数的语言是 Node.js 12.x。确保指定 IAM 角色。此示例使用 `'arn:aws:iam::123456789012:user/johndoe'` 作为 IAM 角色。
```
CREATE EXTERNAL FUNCTION exfunc_sum(INT,INT)
RETURNS INT
VOLATILE
LAMBDA 'lambda_sum'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test';
```
Lambda 函数接受请求负载并对每一行进行迭代。将单行中的所有值相加以计算该行的总和，并将其保存在响应数组中。结果数组中的行数与请求负载中接收的行数相似。
JSON 响应负载必须在“results”字段中包含结果数据，才能被外部函数识别。发送到 Lambda 函数的请求中的参数字段包含数据负载。在批处理请求的情况下，数据负载中可能有多行。以下 Lambda 函数对请求数据负载中的所有行进行迭代。它还分别对一行中的所有值进行迭代。
```
exports.handler = async (event) => {
// The 'arguments' field in the request sent to the Lambda function contains the data payload.
var t1 = event['arguments'];
// 'len(t1)' represents the number of rows in the request payload.
// The number of results in the response payload should be the same as the number of rows received.
const resp = new Array(t1.length);
// Iterating over all the rows in the request payload.
for (const [i, x] of t1.entries())
{
var sum = 0;
// Iterating over all the values in a single row.
for (const y of x) {
sum = sum + y;
}
resp[i] = sum;
}
// The 'results' field should contain the results of the lambda call.
const response = {
results: resp
};
return JSON.stringify(response);
};
```
以下示例使用文本值调用外部函数。
```
select exfunc_sum(1,2);
exfunc_sum
------------
3
(1 row)
```
以下示例创建一个名为 t\$1sum 的表（其中包含整数数据类型的两个列 c1 和 c2）并插入两行数据。然后通过传递此表的列名称来调用外部函数。这两个表行作为单个 Lambda 调用在请求负载中的批处理请求中发送。
```
CREATE TABLE t_sum(c1 int, c2 int);
INSERT INTO t_sum VALUES (4,5), (6,7);
SELECT exfunc_sum(c1,c2) FROM t_sum;
exfunc_sum
---------------
9
13
(2 rows)
```
### 使用 RETRY\$1TIMEOUT 属性的标量 Lambda UDF 示例
在以下部分中，您可以找到如何在 Lambda UDF 中使用 RETRY\$1TIMEOUT 属性的示例。
AWS Lambda 函数具有并发限制，您可以为每个函数设置这些限制。有关并发限制的更多信息，请参阅《AWS Lambda 开发人员指南》**中的[为 Lambda 函数管理并发](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html)和 AWS 计算博客上的博客文章 [Managing AWS Lambda Function Concurrency](https://aws.amazon.com/blogs/compute/managing-aws-lambda-function-concurrency)。
当 Lambda UDF 服务的请求数超过并发限制时，新请求将接收 `TooManyRequestsException` 错误。Lambda UDF 会重试此错误，直到发送到 Lambda 函数的请求之间的所有延迟总和等于或超过您设置的 RETRY\$1TIMEOUT 值。默认的 RETRY\$1TIMEOUT 值为 20000 毫秒。
下面的示例使用一个名为 `exfunc_sleep_3` 的 Lambda 函数。此函数接受请求负载，对每一行进行迭代，并将输入转换为大写。然后它会睡眠 3 秒钟并返回结果。此 Lambda 函数使用的语言是 Python 3.8。
结果数组中的行数与请求负载中接收的行数相似。JSON 响应负载必须在 `results` 字段中包含结果数据，才能被外部函数识别。发送到 Lambda 函数的请求中的 `arguments` 字段包含数据负载。在批处理请求的情况下，数据负载中可能有多行。
在保留并发中，此函数的并发限制被专门设置为 1，以演示 RETRY\$1TIMEOUT 属性的使用情况。当属性设置为 1 时，Lambda 函数一次只能处理一个请求。
```
import json
import time
def lambda_handler(event, context):
t1 = event['arguments']
# 'len(t1)' represents the number of rows in the request payload.
# The number of results in the response payload should be the same as the number of rows received.
resp = [None]*len(t1)
# Iterating over all rows in the request payload.
for i, x in enumerate(t1):
# Iterating over all the values in a single row.
for j, y in enumerate(x):
resp[i] = y.upper()
time.sleep(3)
ret = dict()
ret['results'] = resp
ret_json = json.dumps(ret)
return ret_json
```
以下两个附加示例对 RETRY\$1TIMEOUT 属性进行了说明。它们各自调用了一个 Lambda UDF。在调用 Lambda UDF 时，每个示例都运行相同的 SQL 查询，以便同时从两个并发数据库会话调用 Lambda UDF。当第一个调用 Lambda UDF 的查询由 UDF 提供时，第二个查询会收到 `TooManyRequestsException` 错误。出现此结果是因为您将 UDF 中的保留并发专门设置为 1。有关如何为 Lambda 函数设置保留并发的信息，请参阅[配置预留并发](https://docs.aws.amazon.com/lambda/latest/dg/configuration-concurrency.html#configuration-concurrency-reservedconfiguration-concurrency-reserved)。
下面的第一个示例将 Lambda UDF 的 RETRY\$1TIMEOUT 属性设置为 0 毫秒。如果 Lambda 请求收到来自 Lambda 函数的任何异常，则 Amazon Redshift 不会进行任何重试。出现此结果的原因是 RETRY\$1TIMEOUT 属性被设置为 0。
```
CREATE OR REPLACE EXTERNAL FUNCTION exfunc_upper(varchar)
RETURNS varchar
VOLATILE
LAMBDA 'exfunc_sleep_3'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test'
RETRY_TIMEOUT 0;
```
将 RETRY\$1TIMEOUT 设置为 0 时，您可以从单独的数据库会话运行以下两个查询以查看不同的结果。
使用 Lambda UDF 的第一个 SQL 查询成功运行。
```
select exfunc_upper('Varchar');
exfunc_upper
--------------
VARCHAR
(1 row)
```
同时从单独的数据库会话运行的第二个查询将收到 `TooManyRequestsException` 错误。
```
select exfunc_upper('Varchar');
ERROR: Rate Exceeded.; Exception: TooManyRequestsException; ShouldRetry: 1
DETAIL:
-----------------------------------------------
error: Rate Exceeded.; Exception: TooManyRequestsException; ShouldRetry: 1
code: 32103
context:query: 0
location: exfunc_client.cpp:102
process: padbmaster [pid=26384]
-----------------------------------------------
```
下面的第二个示例将 Lambda UDF 的 RETRY\$1TIMEOUT 属性设置为 3000 毫秒。即使同时运行第二个查询，Lambda UDF 也会重试，直到总延迟为 3000 毫秒。因此，两个查询都成功运行。
```
CREATE OR REPLACE EXTERNAL FUNCTION exfunc_upper(varchar)
RETURNS varchar
VOLATILE
LAMBDA 'exfunc_sleep_3'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test'
RETRY_TIMEOUT 3000;
```
将 RETRY\$1TIMEOUT 被设置为 3000 时，您可以从单独的数据库会话运行以下两个查询以查看相同的结果。
运行 Lambda UDF 的第一个 SQL 查询成功运行。
```
select exfunc_upper('Varchar');
exfunc_upper
--------------
VARCHAR
(1 row)
```
第二个查询同时运行，且 Lambda UDF 重试，直到总延迟为 3000 毫秒。
```
select exfunc_upper('Varchar');
exfunc_upper
--------------
VARCHAR
(1 row)
```
### 使用 Python Lambda 函数的标量 Lambda UDF 示例
以下示例创建名为 `exfunc_multiplication` 的外部函数，然后将数字相乘并返回整数。此示例合并了 Lambda 响应中的 success 和 `error_msg` 字段。当乘法结果中存在整数溢出时，success 字段设置为 false，且 `error_msg` 消息设置为 `Integer multiplication overflow`。`exfunc_multiplication` 函数将三个整数作为输入参数，并将总和作为整数输出返回。
被调用的 Lambda 函数的名称为 `lambda_multiplication`。此 Lambda 函数使用的语言是 Python 3.8。确保指定 IAM 角色。
```
CREATE EXTERNAL FUNCTION exfunc_multiplication(int, int, int)
RETURNS INT
VOLATILE
LAMBDA 'lambda_multiplication'
IAM_ROLE 'arn:aws:iam::123456789012:role/Redshift-Exfunc-Test';
```
Lambda 函数接受请求负载并对每一行进行迭代。将单行中的所有值相乘以计算该行的结果，并将其保存在响应列表中。此示例使用默认设置为 true 的 Boolean success 值。如果行的乘法结果具有整数溢出，则 success 值设置为 false。然后，迭代循环中断。
创建响应负载时，如果 success 值为 false，则以下 Lambda 函数将 `error_msg` 字段添加到负载中。它还将错误消息设置为 `Integer multiplication overflow`。如果 success 值为 true，则结果数据将添加到结果字段中。结果数组（如果有）中的行数与请求负载中接收的行数相似。
发送到 Lambda 函数的请求中的参数字段包含数据负载。在批处理请求的情况下，数据负载中可能有多行。以下 Lambda 函数对请求数据负载中的所有行进行迭代，并分别对一行中的所有值进行迭代。
```
import json
def lambda_handler(event, context):
t1 = event['arguments']
# 'len(t1)' represents the number of rows in the request payload.
# The number of results in the response payload should be the same as the number of rows received.
resp = [None]*len(t1)
# By default success is set to 'True'.
success = True
# Iterating over all rows in the request payload.
for i, x in enumerate(t1):
mul = 1
# Iterating over all the values in a single row.
for j, y in enumerate(x):
mul = mul*y
# Check integer overflow.
if (mul >= 9223372036854775807 or mul <= -9223372036854775808):
success = False
break
else:
resp[i] = mul
ret = dict()
ret['success'] = success
if not success:
ret['error_msg'] = "Integer multiplication overflow"
else:
ret['results'] = resp
ret_json = json.dumps(ret)
return ret_json
```
以下示例使用文本值调用外部函数。
```
SELECT exfunc_multiplication(8, 9, 2);
exfunc_multiplication
---------------------------
144
(1 row)
```
以下示例创建一个名为 t\$1multi 的表，其中包含整数数据类型的三个列 c1、c2 和 c3。通过传递此表的列名称来调用外部函数。以导致整数溢出的方式插入数据，从而显示错误的传播方式。
```
CREATE TABLE t_multi (c1 int, c2 int, c3 int);
INSERT INTO t_multi VALUES (2147483647, 2147483647, 4);
SELECT exfunc_multiplication(c1, c2, c3) FROM t_multi;
DETAIL:
-----------------------------------------------
error: Integer multiplication overflow
code: 32004context:
context:
query: 38
location: exfunc_data.cpp:276
process: query2_16_38 [pid=30494]
-----------------------------------------------
```
# CREATE EXTERNAL MODEL
**Topics**
+ [CREATE EXTERNAL MODEL 的先决条件](#r_create_external_model_prereqs)
+ [所需的权限](#r_simple_create_model-privileges)
+ [成本控制](#r_create_model_cost)
+ [CREATE EXTERNAL MODEL 语法](#r_create_external_model_syntax)
+ [CREATE EXTERNAL MODEL 参数和设置](#r_create_external_model_parameters_settings)
+ [CREATE EXTERNAL MODEL 推理函数参数](#r_create_external_model_if_parameters)
## CREATE EXTERNAL MODEL 的先决条件
在使用 CREATE EXTERNAL MODEL 语句之前，请完成 [用于使用 Amazon Redshift ML 的集群设置](getting-started-machine-learning.md#cluster-setup) 中的先决条件。下面简要概述了这些先决条件。
+ 使用 AWS 管理控制台或 AWS 命令行界面 (AWS CLI) 创建 Amazon Redshift 集群。
+ 在创建集群时附加 AWS Identity and Access Management (IAM) policy。
+ 要允许 Amazon Redshift 和 Amazon Bedrock 代入角色以便与其它服务交互，请向 IAM 角色添加相应的信任策略。
+ 支持从 Amazon Bedrock 控制台访问您要使用的特定 LLM。
+ （可选）如果您遇到来自 Amazon Bedrock 的节流异常（例如 `Too many requests, please wait before trying again`），即使数据量很少，也可以在 Amazon Bedrock 账户的**服务配额**下检查配额。检查所应用的账户级配额是否至少与针对您正在使用的模型的 **InvokeModel** 请求的 AWS 默认配额值相同。
有关 IAM 角色、信任策略和其他先决条件的详细信息，请参阅[用于使用 Amazon Redshift ML 的集群设置](getting-started-machine-learning.md#cluster-setup)。
## 所需的权限
以下是 CREATE EXTERNAL MODEL 所需的权限：
+ Superuser
+ 具有 CREATE MODEL 权限的用户
+ 具有 GRANT CREATE MODEL 权限的角色
## 成本控制
Amazon Redshift ML 使用现有集群资源创建预测模型，因此您无需支付额外费用。不过，AWS 会根据您选择的模型收取使用 Amazon Bedrock 的费用。有关更多信息，请参阅[使用 Amazon Redshift ML 的成本](https://docs.aws.amazon.com/redshift/latest/dg/cost.html)。
## CREATE EXTERNAL MODEL 语法
以下是 CREATE EXTERNAL MODEL 语句的完整语法。
```
CREATE EXTERNAL MODEL model_name
FUNCTION function_name
IAM_ROLE {default/'arn:aws:iam:::role/'}
MODEL_TYPE BEDROCK
SETTINGS (
MODEL_ID model_id
[, PROMPT 'prompt prefix']
[, SUFFIX 'prompt suffix']
[, REQUEST_TYPE {RAW|UNIFIED}]
[, RESPONSE_TYPE {VARCHAR|SUPER}]
);
```
`CREATE EXTERNAL MODEL` 命令会创建一个推理函数，用于生成内容。
下面是 `CREATE EXTERNAL MODEL` 使用 `RAW` `REQUEST_TYPE` 创建的推理函数的语法：
```
SELECT inference_function_name(request_super)
[FROM table];
```
下面是 `CREATE EXTERNAL MODEL` 使用 `UNIFIED` `REQUEST_TYPE` 创建的推理函数的语法：
```
SELECT inference_function_name(input_text, [, inference_config [, additional_model_request_fields]])
[FROM table];
```
有关如何使用推理函数的信息，请参阅 [为 Amazon Redshift ML 与 Amazon Bedrock 的集成使用外部模型](machine-learning-br.md#machine-learning-br-use)。
## CREATE EXTERNAL MODEL 参数和设置
此部分介绍 `CREATE EXTERNAL MODEL` 命令的参数和设置。
**Topics**
+ [CREATE EXTERNAL MODEL 参数](#r_create_external_model_parameters)
+ [CREATE EXTERNAL MODEL 设置](#r_create_external_model_settings)
### CREATE EXTERNAL MODEL 参数
model\$1name
外部模型的名称。schema 中的模型名称必须是唯一的。
FUNCTION *function\$1name (data\$1type [,...] )*
`CREATE EXTERNAL MODEL` 创建的推理函数的名称。您可以使用推理函数向 Amazon Bedrock 发送请求并检索 ML 生成的文本。
IAM\$1ROLE * \$1 default \$1 'arn:aws:iam:::role/' \$1*
Amazon Redshift 用于访问 Amazon Bedrock 的 IAM 角色。有关 IAM 角色的信息，请参阅 [为 Amazon Redshift ML 与 Amazon Bedrock 的集成创建或更新 IAM 角色](machine-learning-br.md#machine-learning-br-iam)。
MODEL\$1TYPE BEDROCK
指定模型类型。唯一有效值为 `BEDROCK`。
SETTINGS ( MODEL\$1ID model\$1id [,...] )
指定外部模型设置。详见下一节。
### CREATE EXTERNAL MODEL 设置
MODEL\$1ID model\$1id
外部模型的标识符，例如 `anthropic.claude-v2`。有关 Amazon Bedrock 模型 ID 的信息，请参阅 [Amazon Bedrock 模型 ID](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html)。
PROMPT 'prompt prefix'
指定 Amazon Redshift 添加到每个推理请求开头的静态提示。只有在 `REQUEST_TYPE` 为 `UNIFIED` 时受支持。
SUFFIX 'prompt suffix'
指定 Amazon Redshift 添加到每个推理请求末尾的静态提示。只有在 `REQUEST_TYPE` 为 `UNIFIED` 时受支持。
REQUEST\$1TYPE \$1 RAW \$1 UNIFIED \$1
指定发送到 Amazon Bedrock 的请求的格式。有效值包括：
+ **RAW**：推理函数以单个 super 值作为输入，并始终返回一个 super 值。super 值的格式取决于所选的 Amazon Bedrock 模型。super 是一种预测模型，它将多种算法结合在一起，产生一个改进的预测结果。
+ **UNIFIED**：推理函数使用统一 API。所有模型都与 Amazon Bedrock 拥有统一一致的接口。这适用于所有支持消息的模型。此值是默认值。
有关更多信息，请参阅 *Amazon Bedrock API 文档*中的 [Converse API 文档](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)。
RESPONSE\$1TYPE \$1 VARCHAR \$1 SUPER \$1
指定响应的格式。如果 `REQUEST_TYPE` 为 `RAW`，则需要 `RESPONSE_TYPE`，而且唯一有效的值为 `SUPER`。对于所有其它 `REQUEST TYPE` 值，默认值为 `VARCHAR`，而且 `RESPONSE_TYPE` 是可选的。有效值包括：
+ **VARCHAR**：Amazon Redshift 仅返回模型生成的文本响应。
+ **SUPER**：Amazon Redshift 会将模型生成的整个响应 JSON 作为 super 返回。这包括文本响应、停止原因等信息，以及模型输入和输出标记的使用情况。super 是一种预测模型，它将多种算法结合在一起，产生一个改进的预测结果。
## CREATE EXTERNAL MODEL 推理函数参数
此部分介绍 `CREATE EXTERNAL MODEL` 命令创建的推理函数的有效参数。
### `REQUEST_TYPE` 为 `RAW` 的 CREATE EXTERNAL MODEL 推理函数参数
当 `REQUEST_TYPE` 为 `RAW` 时创建的推理函数有一个 super 输入参数，并且始终返回 super 数据类型。输入 super 的语法遵循从 Amazon Bedrock 中选择的特定模型的请求语法。
### `REQUEST_TYPE` 为 `UNIFIED` 的 CREATE EXTERNAL MODEL 推理函数参数
input\$1text
Amazon Redshift 发送给 Amazon Bedrock 的文本。
inference\$1config
一个 super 值，其中包含 Amazon Redshift 发送给 Amazon Bedrock 的可选参数。包括以下参数：
+ maxTokens
+ stopSequences
+ temperature
+ topP
这些参数均为可选参数，且区分大小写。有关这些参数的信息，请参阅《Amazon Bedrock API 参考》**中的 [InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html)。
# CREATE EXTERNAL SCHEMA
在当前数据库中创建一个新外部 schema。您可以使用此外部 schema 连接到 Amazon RDS for PostgreSQL 或 Amazon Aurora PostgreSQL 兼容版本数据库。您还可以创建引用外部数据目录（如 AWS Glue、Athena）中的数据库或 Apache Hive 元存储（如 Amazon EMR）中的数据库的外部 schema。
此 schema 的所有者为 CREATE EXTERNAL SCHEMA 命令的发布者。要移交外部 schema 的所有权，请使用 [ALTER SCHEMA](r_ALTER_SCHEMA.md) 更改所有者。要为其他用户或用户组授予架构的访问权限，请使用 [GRANT](r_GRANT.md) 命令。
您无法针对外部表的权限使用 GRANT 或 REVOKE 命令。相反，您可以授予或撤销对外部 schema 的权限。
**注意**
如果您当前在 Amazon Athena 数据目录中有 Redshift Spectrum 外部表，则可以将您的 Athena 数据目录迁移到 AWS Glue Data Catalog。要将 AWS Glue Data Catalog 用于 Redshift Spectrum，您可能需要更改您的 AWS Identity and Access Management (IAM) 策略。有关更多信息，请参阅《Athena 用户指南》**中的[升级到 AWS Glue Data Catalog](https://docs.aws.amazon.com/athena/latest/ug/glue-athena.html#glue-upgrade)。
要查看外部 schema 的详细信息，请查询 [SVV\$1EXTERNAL\$1SCHEMAS](r_SVV_EXTERNAL_SCHEMAS.md) 系统视图。
## 语法
以下语法描述了用于使用外部数据目录引用数据的 CREATE EXTERNAL SCHEMA 命令。有关更多信息，请参阅 [Amazon Redshift Spectrum](c-using-spectrum.md)。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM [ [ DATA CATALOG ] | HIVE METASTORE | POSTGRES | MYSQL | KINESIS | MSK | REDSHIFT | KAFKA ]
[ DATABASE 'database_name' ]
[ SCHEMA 'schema_name' ]
[ REGION 'aws-region' ]
[ IAM_ROLE [ default | 'SESSION' | 'arn:aws:iam:::role/' ] ]
[ AUTHENTICATION [ none | iam | mtls] ]
[ AUTHENTICATION_ARN 'acm-certificate-arn' | SECRET_ARN 'ssm-secret- arn' ]
[ URI ['hive_metastore_uri' [ PORT port_number ] | 'hostname' [ PORT port_number ] | 'Kafka bootstrap URL'] ]
[ CLUSTER_ARN 'arn:aws:kafka:::cluster/msk/' ]
[ CATALOG_ROLE [ 'SESSION' | 'catalog-role-arn-string' ] ]
[ CREATE EXTERNAL DATABASE IF NOT EXISTS ]
[ CATALOG_ID 'Amazon Web Services account ID containing Glue or Lake Formation database' ]
```
以下语法描述了用于使用至 RDS POSTGRES 或 Aurora PostgreSQL 的联合查询引用数据的 CREATE EXTERNAL SCHEMA 命令。您还可以创建引用流式源的外部 Schema，例如 Kinesis Data Streams。有关更多信息，请参阅 [在 Amazon Redshift 中使用联合查询来查询数据](federated-overview.md)。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM POSTGRES
DATABASE 'federated_database_name' [SCHEMA 'schema_name']
URI 'hostname' [ PORT port_number ]
IAM_ROLE [ default | 'arn:aws:iam:::role/' ]
SECRET_ARN 'ssm-secret-arn'
```
以下语法描述了用于使用至 RDS MySQL 或 Aurora MySQL 的联合查询引用数据的 CREATE EXTERNAL SCHEMA 命令。有关更多信息，请参阅 [在 Amazon Redshift 中使用联合查询来查询数据](federated-overview.md)。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] local_schema_name
FROM MYSQL
DATABASE 'federated_database_name'
URI 'hostname' [ PORT port_number ]
IAM_ROLE [ default | 'arn:aws:iam:::role/' ]
SECRET_ARN 'ssm-secret-arn'
```
以下语法描述了用于引用 Kinesis 流中数据的 CREATE EXTERNAL SCHEMA 命令。有关更多信息，请参阅 [流式摄取到实体化视图](materialized-view-streaming-ingestion.md)。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] schema_name
FROM KINESIS
IAM_ROLE [ default | 'arn:aws:iam:::role/' ]
```
以下语法描述了 CREATE EXTERNAL SCHEMA 命令，该命令用于引用 Amazon Managed Streaming for Apache Kafka 或 Confluent Cloud 集群及其要从中摄取的主题。要进行连接，您需要提供代理 URI。有关更多信息，请参阅 [流式摄取到实体化视图](materialized-view-streaming-ingestion.md)。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] schema_name
FROM KAFKA
[ IAM_ROLE [ default | 'arn:aws:iam:::role/' ] ]
URI 'Kafka bootstrap URI'
AUTHENTICATION [ none | iam | mtls ]
[ AUTHENTICATION_ARN 'acm-certificate-arn' | SECRET_ARN 'ssm-secret- arn' ];
```
以下语法描述了用于使用跨 数据库查询引用数据的 CREATE EXTERNAL SCHEMA 命令。
```
CREATE EXTERNAL SCHEMA local_schema_name
FROM REDSHIFT
DATABASE 'redshift_database_name' SCHEMA 'redshift_schema_name'
```
## 参数
IF NOT EXISTS
一个子句，指示如果指定 schema 已存在，则此命令不应进行任何更改，并应返回一条指示 schema 存在的消息，而不是以错误终止。此子句在编写脚本时很有用，可使脚本在 CREATE EXTERNAL SCHEMA 尝试创建已存在的 schema 时不会失败。
local\$1schema\$1name
新外部 schema 的名称。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
FROM [ DATA CATALOG ] \$1 HIVE METASTORE \$1 POSTGRES \$1 MYSQL \$1 KINESIS \$1 MSK \$1 REDSHIFT
指示外部数据库所在位置的关键词。
DATA CATALOG 指示外部数据库是在 Athena 数据目录或 AWS Glue Data Catalog 中定义的。
如果外部数据库是在位于其他 AWS 区域的外部 Data Catalog 中定义的，则 REGION 参数为必填项。DATA CATALOG 是默认值。
HIVE METASTORE 指示外部数据库是在 Apache Hive 元存储中定义的。如果指定了 HIVE METASTORE，则 URI 为必填项。
POSTGRES 指示外部数据库是在 RDS PostgreSQL 或 Aurora PostgreSQL 中定义的。
MYSQL 表示外部数据库是在 RDS MySQL 或 Aurora MySQL 中定义的。
KINESIS 指示数据来源是一个来自 Kinesis Data Streams 的流。
MSK 表示数据来源是 Amazon MSK 预置的集群或无服务器集群。
KAFKA 表示数据来源是 Kafka 集群。您可以对 Amazon MSK 和 Confluent Cloud 使用此关键词。
FROM REDSHIFT
指示数据库位于 Amazon Redshift 中的关键词。
DATABASE“*redshift\$1database\$1name*”SCHEMA“*redshift\$1schema\$1name*”
Amazon Redshift 数据库的名称。
*redshift\$1schema\$1name* 指示 Amazon Redshift 中的 schema。默认的 *redshift\$1schema\$1name* 为 `public`。
数据库“federa*ted\$1database\$1name*”
在支持的 PostgreSQL or MySQL 数据库引擎中指示外部数据库名称的关键词。
[SCHEMA '*schema\$1name*']
*schema\$1name* 指示支持的 PostgreSQL 数据库引擎中的 schema。默认的 *schema\$1name* 是 `public`。
在设置对受支持的 MySQL 数据库引擎的联合查询时，无法指定 SCHEMA。
REGION '*aws-region*'
如果外部数据库是在 Athena 数据目录或 AWS Glue Data Catalog 中定义的，则为数据库所在的 AWS 区域。如果数据库是在外部 Data Catalog 中定义的，则此参数为必填项。
URI [ 'hive\$1metastore\$1uri' [ PORT port\$1number ] \$1 'hostname' [ PORT port\$1number ] \$1 'Kafka bootstrap URI' ]
支持的 PostgreSQL 或 MySQL 数据库引擎的主机名 URI 和 port\$1number。*hostname* 是副本集的头节点。端点必须可以从 Amazon Redshift 集群进行访问（路由）。默认的 PostgreSQL port\$1number 为 5432。默认的 MySQL port\$1number 为 3306。
支持的 PostgreSQL 或 MySQL 数据库引擎必须与 Amazon Redshift 集群位于同一个 VPC 中，而该集群的安全组将 Amazon Redshift 与 RDS url-rsPostgreSQL 或 Aurora PostgreSQL 相关联。此外，可以使用增强型 VPC 路由来配置跨 VPC 用例。有关更多信息，请参阅 [Redshift 托管的 VPC 端点](https://docs.aws.amazon.com/redshift/latest/mgmt/managing-cluster-cross-vpc.html)。
**指定 Hive 元存储 URI**
如果数据库位于 Hive 元存储中，请指定 URI 并选择性地指定元存储的端口号。默认端口号为 9083。
URI 不包含协议规范（“http://”）。有效 URI 示例：`uri '172.10.10.10'`。
**指定用于流式摄取的代理 URI**
包括引导代理 URI，即可连接到 Amazon MSK 或 Confluent Cloud 集群并接收流式传输数据。有关更多信息以及相关示例，请参阅[开始使用 Amazon Managed Streaming for Apache Kafka 流式摄取](https://docs.aws.amazon.com/redshift/latest/dg/materialized-view-streaming-ingestion-getting-started-MSK.html)。
IAM\$1ROLE [ default \$1 'SESSION' \$1 'arn:aws:iam::**:role/**' ]
使用默认关键字让 Amazon Redshift 使用设置为默认值并在 CREATE EXTERNAL SCHEMA 命令运行时与集群关联的 IAM 角色。
如果您使用联合身份连接到 Amazon Redshift 集群并访问使用此命令创建的外部架构中的表，则使用 `'SESSION'`。有关更多信息，请参阅[使用联合身份管理 Amazon Redshift 对本地资源和 Amazon Redshift Spectrum 外部表的访问权限](https://docs.aws.amazon.com/redshift/latest/mgmt/authorization-fas-spectrum.html)，其中说明了如何配置联合身份。请注意，此配置（使用 `'SESSION'` 替代 ARN）仅在使用 `DATA CATALOG` 创建架构时才能使用。
使用 IAM 角色的 Amazon 资源名称（ARN），您的集群使用该角色进行身份验证和授权。IAM 角色至少必须有权在要访问的 Amazon S3 桶上执行 LIST 操作和有权在该桶包含的 Amazon S3 对象上执行 GET 操作。
下面显示了单个 ARN 的 IAM\$1ROLE 参数字符串的语法。
```
IAM_ROLE 'arn:aws:iam:::role/'
```
您可以将角色串联起来，以便集群可以承担另一个 IAM 角色 (可能属于其他账户)。您最多可串联 10 个角色。有关串联角色的示例，请参阅[在 Amazon Redshift Spectrum 中链接 IAM 角色](c-spectrum-iam-policies.md#c-spectrum-chaining-roles)。
对于此 IAM 角色，请附加类似于以下内容的 IAM 权限策略。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessSecret",
"Effect": "Allow",
"Action": [
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:ListSecretVersionIds"
],
"Resource": "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-rds-secret-VNenFy"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"secretsmanager:GetRandomPassword",
"secretsmanager:ListSecrets"
],
"Resource": "*"
}
]
}
```
有关创建 IAM 角色以用于联合查询的步骤，请参阅[创建密钥和 IAM 角色以使用联合查询](federated-create-secret-iam-role.md)。
请不要在链接的角色列表中包含空格。
下面显示了串联三个角色的语法。
```
IAM_ROLE 'arn:aws:iam:::role/,arn:aws:iam:::role/,arn:aws:iam:::role/'
```
SECRET\$1ARN '*ssm-secret-arn*'
使用 AWS Secrets Manager 创建的支持的 PostgreSQL 或 MySQL 数据库引擎密钥的 Amazon 资源名称（ARN）。有关如何创建和检索密钥的 ARN 的信息，请参阅《AWS Secrets Manager User Guide》**中的 [Manage secrets with AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)，以及[在 Amazon Redshift 中检索密钥的 Amazon 资源名称（ARN）](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-secrets-manager-integration-retrieving-secret.html)。
CATALOG\$1ROLE [ 'SESSION' \$1 *catalog-role-arn-string*]
利用 `'SESSION'`，通过使用用于对数据目录进行身份验证和授权的联合身份来连接到 Amazon Redshift 集群。有关完成联合身份的步骤的更多信息，请参阅[使用联合身份管理 Amazon Redshift 对本地资源和 Amazon Redshift Spectrum 外部表的访问权限](https://docs.aws.amazon.com/redshift/latest/mgmt/authorization-fas-spectrum.html)。请注意，仅在 DATA CATALOG 中创建架构时才能使用 `'SESSION'` 角色。
使用 IAM 角色的 Amazon 资源名称（ARN），您的集群使用该角色对数据目录进行身份验证和授权。
如果未指定 CATALOG\$1ROLE，Amazon Redshift 会使用指定的 IAM\$1ROLE。目录角色必须有权限访问 AWS Glue 或 Athena 中的 Data Catalog。有关更多信息，请参阅 [适用于 Amazon Redshift Spectrum 的 IAM 策略](c-spectrum-iam-policies.md)。
下面显示了单个 ARN 的 CATALOG\$1ROLE 参数字符串的语法。
```
CATALOG_ROLE 'arn:aws:iam:::role/'
```
您可以将角色串联起来，以便集群可以承担另一个 IAM 角色 (可能属于其他账户)。您最多可串联 10 个角色。有关更多信息，请参阅 [在 Amazon Redshift Spectrum 中链接 IAM 角色](c-spectrum-iam-policies.md#c-spectrum-chaining-roles)。
串联角色的列表不能包含空格。
下面显示了串联三个角色的语法。
```
CATALOG_ROLE 'arn:aws:iam:::role/,arn:aws:iam:::role/,arn:aws:iam:::role/'
```
CREATE EXTERNAL DATABASE IF NOT EXISTS
一个子句，用于在指定的外部数据库不存在时使用由 DATABASE 参数指定的名称创建外部数据库。如果指定的外部数据库存在，该命令不会进行任何更改。在这种情况下，该命令将返回指示外部数据库存在的消息，而不是以错误终止。
CREATE EXTERNAL DATABASE IF NOT EXISTS 不能与 HIVE METASTORE 一起使用。
要将 CREATE EXTERNAL DATABASE IF NOT EXISTS 与为 AWS Lake Formation 启用的 Data Catalog 搭配使用，需要获得对于 Data Catalog 的 `CREATE_DATABASE` 权限。
CATALOG\$1ID '*Amazon Web Services 账户 ID，包含 Glue 或 Lake Formation 数据库*'
用于存储数据目录数据库的账户 ID。
只有在您计划使用联合身份（用于对数据目录进行身份验证和授权）连接到 Amazon Redshift 集群或 Amazon Redshift Serverless 时，才能通过设置以下任一项来指定 `CATALOG_ID`：
+ `CATALOG_ROLE`到 `'SESSION'`。
+ 将 `IAM_ROLE` 设置为 `'SESSION'`，并将 `'CATALOG_ROLE'` 设置为默认值
有关完成联合身份的步骤的更多信息，请参阅[使用联合身份管理 Amazon Redshift 对本地资源和 Amazon Redshift Spectrum 外部表的访问权限](https://docs.aws.amazon.com/redshift/latest/mgmt/authorization-fas-spectrum.html)。
AUTHENTICATION
为流式摄取定义的身份验证类型。具有身份验证类型的流式摄取使用 Amazon Managed Streaming for Apache Kafka。`AUTHENTICATION` 类型为：
+ **无** – 指定不需要身份验证。这对应于 MSK 上未经身份验证的访问，或者 Apache Kafka 上具有 TLS 的纯文本。
+ **iam** – 指定 IAM 身份验证。选择此选项时，请确保 IAM 角色具有 IAM 身份验证的权限。有关定义外部模式的更多信息，请参阅[从 Apache Kafka 源进行流式摄取入门](materialized-view-streaming-ingestion-getting-started-MSK.md)。
+ **mtls** – 指定双向传输层安全通过促进客户端和服务器之间的身份验证来提供安全通信。在本例中，客户端是 Redshift，服务器是 Amazon MSK。有关使用 mTLS 配置流式摄取的更多信息，请参阅 [使用 mTLS 对来自 Apache Kafka 源的 Redshift 流式摄取进行身份验证](materialized-view-streaming-ingestion-mtls.md)。
AUTHENTICATION\$1ARN
Amazon Redshift 用于通过 Amazon MSK 进行 mtls 身份验证的 AWS Certificate Manager 证书的 ARN。当您选择已签发证书时，ARN 就会出现在 ACM 控制台中。
CLUSTER\$1ARN
对于流式摄取，CLUSTER\$1ARN 是您从中进行流式传输的 Amazon Managed Streaming for Apache Kafka 集群的集群标识符。使用 CLUSTER\$1ARN 时，它需要包含 `kafka:GetBootstrapBrokers` 权限的 IAM 角色策略。此选项是为了向后兼容性而提供的。目前，我们建议使用引导代理 URI 选项连接到 Amazon Managed Streaming for Apache Kafka 集群。有关更多信息，请参阅[流式摄取](https://docs.aws.amazon.com/redshift/latest/dg/materialized-view-streaming-ingestion.html)。
## 使用说明
有关使用 Athena 数据目录时的限制，请参阅《AWS 一般参考》中的 [Athena 限制](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#amazon-athena-limits)。
有关使用 AWS Glue Data Catalog 时的限制，请参阅《AWS 一般参考》中的 [AWS Glue 限制](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_glue)。
这些限制不适用于 Hive 元存储。
每个数据库最多有 9900 个架构。有关更多信息，请参阅《Amazon Redshift 管理指南》**中的[配额和限制](https://docs.aws.amazon.com/redshift/latest/mgmt/amazon-redshift-limits.html)。
要取消注册架构，请使用 [DROP SCHEMA](r_DROP_SCHEMA.md) 命令。
要查看外部架构的详细信息，请查询以下系统视图：
+ [SVV\$1EXTERNAL\$1SCHEMAS](r_SVV_EXTERNAL_SCHEMAS.md)
+ [SVV\$1EXTERNAL\$1TABLES](r_SVV_EXTERNAL_TABLES.md)
+ [SVV\$1EXTERNAL\$1COLUMNS](r_SVV_EXTERNAL_COLUMNS.md)
## 示例
以下示例使用位于美国西部（俄勒冈州）区域的名为 `sampledb` 的数据目录中的数据库，创建一个外部模式。将此示例与 Athena 或 AWS Glue 数据目录结合使用。
```
create external schema spectrum_schema
from data catalog
database 'sampledb'
region 'us-west-2'
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole';
```
以下示例创建一个外部 schema 并新建一个名为 `spectrum_db` 的新外部数据库。
```
create external schema spectrum_schema
from data catalog
database 'spectrum_db'
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole'
create external database if not exists;
```
以下示例创建一个使用名为 `hive_db` 的 Hive 元存储数据库的外部 schema。
```
create external schema hive_schema
from hive metastore
database 'hive_db'
uri '172.10.10.10' port 99
iam_role 'arn:aws:iam::123456789012:role/MySpectrumRole';
```
以下示例将角色串联起来，以使用角色 `myS3Role` 来访问 Amazon S3 ，并且使用 `myAthenaRole` 进行数据目录访问。有关更多信息，请参阅 [在 Amazon Redshift Spectrum 中链接 IAM 角色](c-spectrum-iam-policies.md#c-spectrum-chaining-roles)。
```
create external schema spectrum_schema
from data catalog
database 'spectrum_db'
iam_role 'arn:aws:iam::123456789012:role/myRedshiftRole,arn:aws:iam::123456789012:role/myS3Role'
catalog_role 'arn:aws:iam::123456789012:role/myAthenaRole'
create external database if not exists;
```
以下示例创建引用 Aurora PostgreSQL 数据库的外部 schema。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] myRedshiftSchema
FROM POSTGRES
DATABASE 'my_aurora_db' SCHEMA 'my_aurora_schema'
URI 'endpoint to aurora hostname' PORT 5432
IAM_ROLE 'arn:aws:iam::123456789012:role/MyAuroraRole'
SECRET_ARN 'arn:aws:secretsmanager:us-east-2:123456789012:secret:development/MyTestDatabase-AbCdEf'
```
以下示例创建一个外部架构来引用导入到使用者集群上的 sales\$1db。
```
CREATE EXTERNAL SCHEMA sales_schema FROM REDSHIFT DATABASE 'sales_db' SCHEMA 'public';
```
以下示例创建引用 Aurora MySQL 数据库的外部 schema。
```
CREATE EXTERNAL SCHEMA [IF NOT EXISTS] myRedshiftSchema
FROM MYSQL
DATABASE 'my_aurora_db'
URI 'endpoint to aurora hostname'
IAM_ROLE 'arn:aws:iam::123456789012:role/MyAuroraRole'
SECRET_ARN 'arn:aws:secretsmanager:us-east-2:123456789012:secret:development/MyTestDatabase-AbCdEf'
```
# CREATE EXTERNAL TABLE
在指定 schema 中创建一个新外部表。所有外部表必须在外部 schema 中创建。外部 schema 和外部表不支持搜索路径。有关更多信息，请参阅 [CREATE EXTERNAL SCHEMA](r_CREATE_EXTERNAL_SCHEMA.md)。
除了使用 CREATE EXTERNAL TABLE 命令创建的外部表之外，Amazon Redshift 还可引用在 AWS Glue 或 AWS Lake Formation 目录或 Apache Hive 元存储中定义的外部表。使用 [CREATE EXTERNAL SCHEMA](r_CREATE_EXTERNAL_SCHEMA.md) 命令可注册在外部目录中定义的外部数据库并使外部表可在 Amazon Redshift 中使用。如果外部表已存在于 AWS Glue 或 AWS Lake Formation 目录或 Hive 元存储中，您无需使用 CREATE EXTERNAL TABLE 创建该表。要查看外部表，请查询 [SVV\$1EXTERNAL\$1TABLES](r_SVV_EXTERNAL_TABLES.md) 系统视图。
通过运行 CREATE EXTERNAL TABLE AS 命令，可以根据查询中的列定义创建外部表，并将该查询的结果写入 Amazon S3 中。结果采用 Apache Parquet 或分隔的文本格式。如果外部表具有一个或多个分区键，Amazon Redshift 会根据这些分区键对新文件进行分区，并自动将新分区注册到外部目录中。有关 CREATE EXTERNAL TABLE AS 的更多信息，请参阅[使用说明](r_CREATE_EXTERNAL_TABLE_usage.md)。
您可使用用于其他 Amazon Redshift 表的同一 SELECT 语法查询外部表。您还可以使用 INSERT 语法将新文件写入 Amazon S3 上外部表的位置。有关更多信息，请参阅 [INSERT（外部表）](r_INSERT_external_table.md)。
要使用外部表创建视图，请在 [CREATE VIEW](r_CREATE_VIEW.md) 语句中包含 WITH NO SCHEMA BINDING 子句。
您无法在事务 (BEGIN … END) 内运行 CREATE EXTERNAL TABLE。有关事务的更多信息，请参阅 [Amazon Redshift 中的隔离级别](c_serial_isolation.md)。
## 所需的权限
要创建外部表，您必须是外部 schema 的所有者或是超级用户。要移交外部 schema 的所有权，请使用 ALTER SCHEMA 更改所有者。对外部表的访问由对外部 schema 的访问权限控制。您无法对外部表的权限执行 [GRANT](r_GRANT.md) 或 [REVOKE](r_REVOKE.md) 操作。但是，您可授予或撤销对外部 schema 的 USAGE 权限。
[使用说明](r_CREATE_EXTERNAL_TABLE_usage.md) 包含有关外部表特定权限的更多信息。
## 语法
```
CREATE EXTERNAL TABLE
external_schema.table_name
(column_name data_type [, …] )
[ PARTITIONED BY (col_name data_type [, … ] )]
[ { ROW FORMAT DELIMITED row_format |
ROW FORMAT SERDE 'serde_name'
[ WITH SERDEPROPERTIES ( 'property_name' = 'property_value' [, ...] ) ] } ]
STORED AS file_format
LOCATION { 's3://bucket/folder/' | 's3://bucket/manifest_file' }
[ TABLE PROPERTIES ( 'property_name'='property_value' [, ...] ) ]
```
以下是 CREATE EXTERNAL TABLE AS 的语法。
```
CREATE EXTERNAL TABLE
external_schema.table_name
[ PARTITIONED BY (col_name [, … ] ) ]
[ ROW FORMAT DELIMITED row_format ]
STORED AS file_format
LOCATION { 's3://bucket/folder/' }
[ TABLE PROPERTIES ( 'property_name'='property_value' [, ...] ) ]
AS
{ select_statement }
```
## 参数
*external\$1schema.table\$1name*
要创建的表的名称（由外部 schema 名称进行限定）。外部表必须在外部 schema 中创建。有关更多信息，请参阅 [CREATE EXTERNAL SCHEMA](r_CREATE_EXTERNAL_SCHEMA.md)。
表名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。您可以使用 UTF-8 多字节字符，每个字符最多为四个字节。Amazon Redshift 对每个集群强制实施 9900 个表的限制，包括用户定义的临时表以及查询处理或系统维护期间由 Amazon Redshift 创建的临时表。您也可以使用数据库名称限定表名称。在下面的示例中，`spectrum_db` 是数据库名称，`spectrum_schema` 是外部 schema 名称，而 `test` 是表名称。
```
create external table spectrum_db.spectrum_schema.test (c1 int)
stored as parquet
location 's3://amzn-s3-demo-bucket/myfolder/';
```
如果指定数据库或 schema 不存在，则不会创建表，并且语句将返回错误。您无法在系统数据库 `template0`、`template1`、`padb_harvest` 或 `sys:internal` 中创建表或视图。
表名称对于指定 schema 必须是唯一名称。
有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
( *column\$1name* *data\$1type* )
要创建的每个列的名称和数据类型。
列名称的最大长度为 127 个字节；更长的名称将被截断为 127 个字节。您可以使用 UTF-8 多字节字符，每个字符最多为四个字节。不能指定列名称 `"$path"` 或 `"$size"`。有关有效名称的更多信息，请参阅[名称和标识符](r_names.md)。
预设情况下，Amazon Redshift 使用伪列 `$path` 和 `$size` 创建外部表。您可以通过将 `spectrum_enable_pseudo_columns` 配置参数设置为 `false` 来禁用为会话创建 pseudocolumns 的功能。有关更多信息，请参阅 [Pseudocolumns](r_CREATE_EXTERNAL_TABLE_usage.md#r_CREATE_EXTERNAL_TABLE_usage-pseudocolumns)。
如果已启用 pseudocolumns，则可在单个表中定义的最大列数为 1598。如果未启用 pseudocolumns，则可在单个表中定义的最大列数为 1600。
如果您创建的是“宽表”，请确保在加载和查询处理期间，不要让列列表超出中间结果的行宽度边界。有关更多信息，请参阅 [使用说明](r_CREATE_TABLE_NEW.md#r_CREATE_TABLE_usage)。
对于 CREATE EXTERNAL TABLE AS 命令，不需要列的列表，因为列是从查询派生的。
*data\$1type*
支持以下[数据类型](c_Supported_data_types.md)：
+ SMALLINT (INT2)
+ INTEGER (INT, INT4)
+ BIGINT (INT8)
+ DECIMAL (NUMERIC)
+ REAL (FLOAT4)
+ DOUBLE PRECISION (FLOAT8)
+ BOOLEAN (BOOL)
+ CHAR (CHARACTER)
+ VARCHAR (CHARACTER VARYING)
+ VARBYTE (CHARACTER VARYING) – 可与 Parquet 和 ORC 数据文件一起使用，并且只能用于非分区表。
+ DATE – 只能与文本、Parquet 或 ORC 数据文件一起使用，或者用作分区列。
+ TIMESTAMP
对于 DATE，您可以使用以下所示的格式。对于使用数字表示的月份值，支持以下格式：
+ `mm-dd-yyyy` - 例如：`05-01-2017`这是默认模式。
+ `yyyy-mm-dd`，其中年份由 2 位以上的数字表示。例如 `2017-05-01`。
对于使用三个字母缩写表示的月份值，则支持以下格式：
+ `mmm-dd-yyyy` - 例如：`may-01-2017`这是默认模式。
+ `dd-mmm-yyyy`，其中年份由 2 位以上的数字表示。例如 `01-may-2017`。
+ `yyyy-mmm-dd`，其中年份由 2 位以上的数字表示。例如 `2017-may-01`。
对于始终小于 100 的年份值，请按以下方式计算年份：
+ 如果年份值小于 70，则在计算年份时加上 2000。例如，以 `mm-dd-yyyy` 格式表示的日期 05-01-17 将被转换为 `05-01-2017`。
+ 如果年份值小于 100 但大于 69，则在计算年份时加上 1900。例如，以 `mm-dd-yyyy` 格式表示的日期 05-01-89 将被转换为 `05-01-1989`。
+ 对于以两位数表示的年份值，请添加前导零，以 4 位数表示年份。
文本文件中的时间戳值的格式必须为 `yyyy-mm-dd HH:mm:ss.SSSSSS`，如以下时间戳值所示：`2017-05-01 11:30:59.000000`。
VARCHAR 列的长度的定义单位是字节而不是字符。例如，VARCHAR(12) 列可包含 12 个单字节字符或 6 个双字节字符。查询外部表时，将截断结果以适合定义的列大小，而不返回错误。有关更多信息，请参阅 [存储和范围](r_Character_types.md#r_Character_types-storage-and-ranges)。
为获得最佳性能，我们建议您指定适合您数据的最小列大小。要查找列中值的最大大小（以字节为单位），请使用 [OCTET\$1LENGTH](r_OCTET_LENGTH.md) 函数。以下示例返回电子邮件列中值的大小上限。
```
select max(octet_length(email)) from users;
max
---
62
```
PARTITIONED BY (*col\$1name* *data\$1type* [, … ] )
用于定义包含一个或多个分区列的已分区表的子句。单独的数据目录用于每个指定的组合，这在某些情况下可提高查询性能。已分区列在表数据本身中不存在。如果您将与表列相同的某个值用于 *col\$1name*，则会产生错误。
创建分区表后，使用 [ALTER TABLE](r_ALTER_TABLE.md) … ADD PARTITION 语句更改表，以将新分区注册到外部目录。在添加分区时，您应定义包含分区数据的子文件夹在 Amazon S3 上的位置。
例如，如果表 `spectrum.lineitem_part` 是使用 `PARTITIONED BY (l_shipdate date)` 定义的，请运行以下 ALTER TABLE 命令来添加分区。
```
ALTER TABLE spectrum.lineitem_part ADD PARTITION (l_shipdate='1992-01-29')
LOCATION 's3://spectrum-public/lineitem_partition/l_shipdate=1992-01-29';
```
如果您使用 CREATE EXTERNAL TABLE AS，则不需要运行 ALTER TABLE...ADD PARTITION。Amazon Redshift 会自动在外部目录中注册新分区。Amazon Redshift 还会根据表中定义的一个或多个分区键自动将相应的数据写入 Amazon S3 中的分区。
要查看分区，请查询 [SVV\$1EXTERNAL\$1PARTITIONS](r_SVV_EXTERNAL_PARTITIONS.md) 系统视图。
对于 CREATE EXTERNAL TABLE AS 命令，您不需要指定分区列的数据类型，因为此列是从查询派生的。
ROW FORMAT DELIMITED *rowformat*
用于指定基础数据的格式的子句。*rowformat* 的可能值如下所示：
+ LINES TERMINATED BY '*delimiter*'
+ FIELDS TERMINATED BY '*delimiter*'
为 '*delimiter*' 指定一个 ASCII 字符。您可以指定使用八进制格式的非打印 ASCII 字符，具体格式为 `'\`*`ddd`*`'`，其中 *`d`* 是一个八进制数（0–7），最大为“\$1177”。以下示例使用八进制形式指定 BEL（响铃）字符。
```
ROW FORMAT DELIMITED FIELDS TERMINATED BY '\007'
```
如果省略了 ROW FORMAT，则默认格式为 DELIMITED FIELDS TERMINATED BY '\$1A'（标题开头）和 LINES TERMINATED BY '\$1n'（换行符）。
ROW FORMAT SERDE '*serde\$1name*'[WITH SERDEPROPERTIES ( '*property\$1name*' = '*property\$1value*' [, ...] ) ]
用于为基础数据指定 SERDE 格式的子句。
'*serde\$1name*'
SerDe 的名称。您可以指定以下格式：
+ org.apache.hadoop.hive.serde2.RegexSerDe
+ com.amazonaws.glue.serde.GrokSerDe
+ org.apache.hadoop.hive.serde2.OpenCSVSerde
此参数支持 OpenCSVSerde 的以下 SerDe 属性：
```
'wholeFile' = 'true'
```
将 `wholeFile` 属性设置为 `true`，以正确解析 OpenCSV 请求的引号字符串中的新行字符 (\$1n)。
+ org.openx.data.jsonserde.JsonSerDe
+ JSON SERDE 还支持 Ion 文件。
+ JSON 必须格式正确。
+ Ion 和 JSON 中的时间戳必须使用 ISO8601 格式。
+ 该参数支持 JsonSerDe 的以下 SerDe 属性：
```
'strip.outer.array'='true'
```
处理 Ion/JSON 文件，其中包含一个包含在方括号 ( [ … ] ) 中的非常大的数组，就像它在数组中包含多个 JSON 记录一样。
+ com.amazon.ionhiveserde.IonHiveSerDe
除数据类型外，Amazon ION 格式还提供文本和二进制格式。对于引用 ION 格式数据的外部表，将外部表中的每个列映射到 ION 格式数据中的对应元素。有关更多信息，请参阅 [Amazon Ion](https://amzn.github.io/ion-docs/)。此外，您还需要指定输入和输出格式。
WITH SERDEPROPERTIES ( '*property\$1name*' = '*property\$1value*' [, ...] ) ]
（可选）指定以逗号分隔的属性名称和值。
如果省略了 ROW FORMAT，则默认格式为 DELIMITED FIELDS TERMINATED BY '\$1A'（标题开头）和 LINES TERMINATED BY '\$1n'（换行符）。
STORED AS *file\$1format*
数据文件的文件格式。
有效格式如下所示：
+ PARQUET
+ RCFILE (仅针对使用 ColumnarSerDe 而不是 LazyBinaryColumnarSerDe 的数据)
+ SEQUENCEFILE
+ TEXTFILE（针对文本文件，包括 JSON 文件）。
+ ORC
+ AVRO
+ INPUTFORMAT '*input\$1format\$1classname*' OUTPUTFORMAT '*output\$1format\$1classname*'
CREATE EXTERNAL TABLE AS 命令只支持两种文件格式：TEXTFILE 和 PARQUET。
对于 INPUTFORMAT 和 OUTPUTFORMAT，指定类名称，如下例所示。
```
'org.apache.hadoop.mapred.TextInputFormat'
```
LOCATION \$1 's3://*bucket/folder*/' \$1 's3://*bucket/manifest\$1file*'\$1
包含数据文件的 Amazon S3 桶或文件夹的路径或包含 Amazon S3 对象路径列表的清单文件。桶必须与 Amazon Redshift 集群位于同一 AWS 区域。有关受支持的 AWS 区域的列表，请参阅[Amazon Redshift Spectrum 限制](c-spectrum-considerations.md)。
如果路径指定桶或文件夹，例如 `'s3://amzn-s3-demo-bucket/custdata/'`，Redshift Spectrum 会扫描指定的桶或文件夹和任意子文件夹中的文件。Redshift Spectrum 将忽略隐藏文件和以句点或下划线开头的文件。
如果路径指定清单文件，则 `'s3://bucket/manifest_file'` 参数必须显式引用单个文件，例如 `'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", "meta": { "content_length": 5956875 } },
{"url":"s3://amzn-s3-demo-bucket1/custdata.2", "meta": { "content_length": 5997091 } },
{"url":"s3://amzn-s3-demo-bucket2/custdata.1", "meta": { "content_length": 5978675 } }
]
}
```
您可以强制包含特定文件。为此，请在清单中的文件级别包含一个 `mandatory` 选项。当您查询缺少强制性文件的外部表时，SELECT 语句将失败。确保外部表定义中包含的所有文件都存在。如果它们并非全部存在，则会显示一个错误，显示未找到的第一个强制性文件。以下示例显示 `mandatory` 选项设置为 `true` 的清单的 JSON。
```
{
"entries": [
{"url":"s3://amzn-s3-demo-bucket1/custdata.1", "mandatory":true, "meta": { "content_length": 5956875 } },
{"url":"s3://amzn-s3-demo-bucket1/custdata.2", "mandatory":false, "meta": { "content_length": 5997091 } },
{"url":"s3://amzn-s3-demo-bucket2/custdata.1", "meta": { "content_length": 5978675 } }
]
}
```
要引用使用 UNLOAD 创建的文件，您可以使用通过 [UNLOAD](r_UNLOAD.md) 和 MANIFEST 参数创建的清单。该清单文件与 [从 Amazon S3 执行 COPY 操作](copy-parameters-data-source-s3.md) 的清单文件兼容，但使用不同的密钥。不使用的密钥会被忽略。
TABLE PROPERTIES ( '*property\$1name*'='*property\$1value*' [, ...] )
用于设置表属性的表定义的子句。
表属性区分大小写。
'compression\$1type'='*value*'
一个属性，它在文件名不包含扩展名时设置要使用的压缩类型。如果您设置此属性且存在文件扩展名，则将忽略该扩展名，并使用由此属性设置的值。压缩类型的有效值如下：
+ bzip2
+ gzip
+ 无
+ snappy
'data\$1cleansing\$1enabled'='true / false’
该属性设置该表的数据处理是否已启用。当“data\$1cleansing\$1enabled”设置为 true 时，表的数据处理将启用。当“data\$1cleansing\$1enabled”设置为 false 时，表的数据处理将关闭。以下是由此属性控制的表级别数据处理属性的列表：
+ column\$1count\$1mismatch\$1handling
+ invalid\$1char\$1handling
+ numeric\$1overflow\$1handling
+ replacement\$1char
+ surplus\$1char\$1handling
有关示例，请参阅 [数据处理示例](r_CREATE_EXTERNAL_TABLE_examples.md#r_CREATE_EXTERNAL_TABLE_examples-data-handling)。
'invalid\$1char\$1handling'='*value*'
指定当查询结果包含无效的 UTF-8 字符值时要执行的操作。您可以指定以下操作：
DISABLED
不执行无效字符处理。
FAIL
取消返回包含无效 UTF-8 值的数据的查询。
SET\$1TO\$1NULL
将无效 UTF-8 值替换为 null。
DROP\$1ROW
将行中的每个值替换为 null。
REPLACE
使用 `replacement_char`，将无效字符替换为您指定的替换字符。
'replacement\$1char'='*character*’
当您将 `invalid_char_handling` 设置为 `REPLACE` 时，请指定要使用的替换字符。
'numeric\$1overflow\$1handling'='value’
指定 ORC 数据包含大于列定义（例如，SMALLINT 或 int16）的整数（例如，BIGINT 或 int64）时要执行的操作。您可以指定以下操作：
DISABLED
关闭无效字符处理。
FAIL
当数据包含无效字符时取消查询。
SET\$1TO\$1NULL
将无效字符设置为 null。
DROP\$1ROW
将行中的每个值设置为 null。
'surplus\$1bytes\$1handling'='*value*'
指定如何处理加载的数据，其长度超过为包含 VARBYTE 数据的列所定义的数据类型的长度。默认情况下，对于超出列宽度的数据，Redshift Spectrum 会将该值设置为 null。
当查询返回超过数据类型长度的数据时，您可以指定以下要执行的操作：
SET\$1TO\$1NULL
将超过列宽度的数据替换为 null。
DISABLED
不执行超额字节处理。
FAIL
取消返回超过列宽度的数据的查询。
DROP\$1ROW
剔除包含超过列宽度的数据的所有行。
TRUNCATE
移除超出列定义的最大字符数的字符。
'surplus\$1char\$1handling'='*value*'
指定如何处理加载的数据，其长度超过包含 VARCHAR、CHAR 或字符串数据列所定义的数据类型长度。默认情况下，对于超出列宽度的数据，Redshift Spectrum 会将该值设置为 null。
当查询返回超过列宽的数据时，您可以指定以下要执行的操作：
SET\$1TO\$1NULL
将超过列宽度的数据替换为 null。
DISABLED
不执行超额字符处理。
FAIL
取消返回超过列宽度的数据的查询。
DROP\$1ROW
将行中的每个值替换为 null。
TRUNCATE
移除超出列定义的最大字符数的字符。
'column\$1count\$1mismatch\$1handling'='value’
确定文件包含的行值是否小于或大于外部表定义中指定的列数。此属性仅适用于未压缩的文本文件格式。您可以指定以下操作：
DISABLED
列计数不匹配处理处于关闭状态。
FAIL
如果检测到列计数不匹配，则查询失败。
SET\$1TO\$1NULL
使用 NULL 填充缺失值并忽略每行中的其他值。
DROP\$1ROW
剔除包含扫描中列计数不匹配错误的所有行。
'numRows'='*row\$1count*'
用于为表定义设置 numRows 值的属性。若要显式更新外部表的统计数据，请设置 numRows 属性来指示表的大小。Amazon Redshift 不分析外部表来生成表统计数据，查询优化程序会使用这些统计数据来生成查询计划。如果没有为外部表设置表统计数据，则 Amazon Redshift 假设外部表是较大的表，本地表是较小的表，以此来生成查询执行计划。
'skip.header.line.count'='*line\$1count*'
用于设置在每个源文件开头要跳过的行数的属性。
'serialization.null.format'=' '
一个属性，指定当存在与某个字段中提供的文本完全匹配的项时，Spectrum 应返回 `NULL` 值。
'orc.schema.resolution'='mapping\$1type'
一个属性，用于设置使用 ORC 数据格式的表的列映射类型。其他数据格式将忽略此属性。
列映射类型的有效值如下：
+ 名称
+ position
如果省略 *orc.schema.resolution* 属性，默认情况下会按名称映射列。如果将 *orc.schema.resolution* 设置为*“name”*或*“position”*之外的任何其他值，则按位置映射列。有关列映射的更多信息，请参阅[将外部表列映射到 ORC 列](c-spectrum-external-tables.md#c-spectrum-column-mapping-orc)。
COPY 命令仅按位置映射到 ORC 数据文件。*orc.schema.resolution* 表属性对 COPY 命令行为无效。
'write.parallel'='on / off’
一个属性，用于设置是否 CREATE EXTERNAL TABLE AS 应并行写入数据。默认情况下，CREATE EXTERNAL TABLE AS 根据集群中的切片数量将数据并行写入到多个文件。默认选项为打开。当“write.parallel”设置为关闭时，CREATE EXTERNAL TABLE AS 以串行方式将一个或多个数据文件写入到 Amazon S3。该表属性还适用于指向同一外部表的所有后续 INSERT 语句。
‘write.maxfilesize.mb’=‘size’
设置由 CREATE EXTERNAL TABLE AS 写入到 Amazon S3 中的每个文件的最大大小（以 MB 为单位）的属性。大小必须是介于 5 到 6200 之间的有效整数。默认最大文件大小为 6,200 MB。该表属性还适用于指向同一外部表的所有后续 INSERT 语句。
‘write.kms.key.id’=‘*value*’
您可以指定一个 AWS Key Management Service 密钥，为 Amazon S3 对象启用服务器端加密 (SSE)，其中 *value* 为以下值之一：
+ `auto`，使用存储在 Amazon S3 桶中的默认 AWS KMS 密钥。
+ *kms-key*，用于指定加密数据。
*select\$1statement*
通过定义任何查询将一行或多行插入外部表的语句。查询生成的所有行都将根据表定义以文本或 Parquet 格式写入到 Amazon S3。
## 示例
[示例](r_CREATE_EXTERNAL_TABLE_examples.md) 中提供了一系列示例。
# 使用说明
本主题包含 [CREATE EXTERNAL TABLE](r_CREATE_EXTERNAL_TABLE.md) 的用法说明。您无法使用用于标准 Amazon Redshift 表（如 [PG\$1TABLE\$1DEF](r_PG_TABLE_DEF.md)、[STV\$1TBL\$1PERM](r_STV_TBL_PERM.md)、PG\$1CLASS 或 information\$1schema）的同一资源查看 Amazon Redshift Spectrum 表的详细信息。如果您的商业智能或分析工具无法识别 Redshift Spectrum 外部表，请将您的应用程序为配置查询 [SVV\$1EXTERNAL\$1TABLES](r_SVV_EXTERNAL_TABLES.md) 和 [SVV\$1EXTERNAL\$1COLUMNS](r_SVV_EXTERNAL_COLUMNS.md)。
## CREATE EXTERNAL TABLE AS
在某些情况下，您可能会对 AWS Glue Data Catalog、AWS Lake Formation 外部目录或 Apache Hive 元存储运行 CREATE EXTERNAL TABLE AS 命令。在这种情况下，您使用 AWS Identity and Access Management (IAM) 角色创建外部架构。此 IAM 角色必须同时具有在 Amazon S3 上读取和写入的权限。
如果您使用 Lake Formation 目录，则 IAM 角色必须具有在目录中创建表的权限。在这种情况下，它还必须对目标 Amazon S3 路径具有数据湖位置权限。此 IAM 角色成为新 AWS Lake Formation 表的所有者。
为确保文件名是唯一的，Amazon Redshift 预设情况下对上载到 Amazon S3 的每个文件的名称使用以下格式。
`_