ALTER TABLE（事件表）¶

修改现有 :doc:` 事件表 </developer-guide/logging-tracing/event-table-setting-up>` 的属性、列或约束条件。

另请参阅：: CREATE EVENT TABLE、DROP TABLE、SHOW EVENT TABLES、DESCRIBE EVENT TABLE

语法¶

ALTER TABLE [ IF EXISTS ] <name> RENAME TO <new_table_name>

ALTER TABLE [ IF EXISTS ] <name> clusteringAction

ALTER TABLE [ IF EXISTS ] <name> dataGovnPolicyTagAction

ALTER TABLE [ IF EXISTS ] <name> searchOptimizationAction

ALTER TABLE [ IF EXISTS ] <name> SET
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE  } ]
  [ CONTACT <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ]
  [ COMMENT = '<string_literal>' ]

ALTER TABLE [ IF EXISTS ] <name> UNSET {
                                       DATA_RETENTION_TIME_IN_DAYS         |
                                       MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                       CHANGE_TRACKING                     |
                                       CONTACT <purpose>                   |
                                       COMMENT                             |
                                       }

其中：

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]

  }

有关详细信息，请参阅搜索优化操作 (searchOptimizationAction)。

参数¶

name

要更改的事件表的标识符。如果标识符包含空格或特殊字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

RENAME TO new_table_name

使用当前未被架构中的任何其他事件表使用的新标识符重命名指定的事件表。

备注

在默认事件表 SNOWFLAKE.TELEMETRY.EVENTS 上不受支持。

有关事件表标识符的更多详细信息，请参阅标识符要求。

可以将对象移动到其他数据库和/或架构，同时选择重命名对象。为此，请指定一个限定 new_name 值，该值分别以 db_name.schema_name.object_name 或 schema_name.object_name 的形式包含新数据库和/或架构名称。

备注

目标数据库和/或架构必须已存在。此外，新位置中不能存在同名对象；否则，该语句将返回错误。
除非对象所有者（即拥有对象 OWNERSHIP 权限的角色）也拥有目标架构，否则禁止将对象移动到托管访问架构。

重命名对象（表、列等）时，引用该对象的其他对象必须使用新名称进行更新。

SET ...

指定要为事件表设置的一个或多个属性/参数（用空格、逗号或新行分隔）：

DATA_RETENTION_TIME_IN_DAYS = integer

对象级参数，用于修改 Time Travel 事件表的保留期。有关更多详细信息，请参阅了解和使用 Time Travel 和使用临时表和瞬态表。

有关此参数的详细说明以及有关对象参数的更多信息，请参阅参数。

值：

Standard Edition：0 或 1

Enterprise Edition：

0 至 90 用于永久事件表

0 或 1 用于临时表和瞬态事件表

备注

值为 0 时会有效禁用事件表的 Time Travel。

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

对象参数，指定 Snowflake 可以延长事件表的数据保留期以防止事件表上的流过时的最大天数。

有关此参数的详细说明，请参阅 MAX_DATA_EXTENSION_TIME_IN_DAYS。

CHANGE_TRACKING = TRUE | FALSE

指定对事件表启用或禁用更改跟踪。

TRUE 在事件表上启用更改跟踪。此选项将一对隐藏列添加到源事件表中，并开始在列中存储更改跟踪元数据。这些列会占用少量存储空间。

可以使用 SELECT 语句的 CHANGES 子句查询更改跟踪元数据，也可以通过在事件表上创建和查询一个或多个流来查询更改跟踪元数据。
FALSE 禁用事件表上的更改跟踪。从事件表中删除一对隐藏列。

CONTACT purpose = contact [ , purpose = contact ... ]

将现有对象与一个或多个联系人关联起来。

您不能在同一语句中使用其他属性设置 CONTACT 属性。

COMMENT = 'string_literal': 添加注释或覆盖事件表的现有注释。

UNSET ...

指定要为事件表取消设置的一个或多个属性/参数，这会将它们重置回默认值：

DATA_RETENTION_TIME_IN_DAYS
MAX_DATA_EXTENSION_TIME_IN_DAYS
CHANGE_TRACKING
CONTACT purpose
COMMENT

您不能在同一语句中使用其他属性取消设置 CONTACT 属性。

数据治理策略和标签操作 (`dataGovnPolicyTagAction`)¶

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

指定标签名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅 Tag quotas。

policy_name: 策略的标识符；对于架构必须是唯一的。

以下子句适用于支持行访问策略的所有表类型，包括但不限于表、视图和事件表。简而言之，这些子句仅指“表”。

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])
向表中添加行访问策略。

必须至少指定一个列名称。可以使用逗号分隔每个列名称来指定其他列。使用此表达式可以向事件表和外部表添加行访问策略。

DROP ROW ACCESS POLICY policy_name
从表中删除行访问策略。

使用此子句将策略从表中删除。

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )
在单个 SQL 语句中，删除在表上设置的行访问策略，并向同一个表添加行访问策略。

DROP ALL ROW ACCESS POLICIES
从表中删除所有行访问策略关联。

在从事件表中删除策略之前，从架构中删除行访问策略时，此表达式非常有用。使用此表达式从表中删除行访问策略关联。

Suppose that a row access policy applied to the table when the backup was created, and the policy was later dropped. After you restore the table from a backup, you can't query it until you run an ALTER TABLE command with the DROP ALL ROW ACCESS POLICIES clause.

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]
为该表分配聚合策略。

使用可选的 ENTITY KEY 参数来定义表中哪些列可以唯一地标识实体。有关更多信息，请参阅通过聚合策略实施实体级隐私。

使用可选 FORCE 参数以原子方式将现有聚合策略替换为新的聚合策略。

UNSET AGGREGATION POLICY
从表中分离聚合策略。

SET JOIN POLICY policy_name

[ FORCE ]
为表分配联接策略。

使用可选 FORCE 参数以原子方式将现有联接策略替换为新的联接策略。

UNSET JOIN POLICY
从表中分离联接策略。

群集操作 (`clusteringAction`)¶

CLUSTER BY ( expr [ , expr , ... ] ): 指定（或修改）一个或多个事件表列或列表达式作为事件表的群集密钥。这些是自动聚类维护聚类的列/表达式。

重要

群集密钥并非旨在或建议用于所有事件表；它们通常有利于非常大（即多 TB）的事件表。

在为事件表指定群集密钥之前，请参阅了解 Snowflake 表结构。
SUSPEND | RESUME RECLUSTER: 启用或禁用自动聚类事件表。
DROP CLUSTERING KEY: 删除事件表的群集密钥。

有关群集密钥和重聚类的更多信息，请参阅了解 Snowflake 表结构。

搜索优化操作 (`searchOptimizationAction`)¶

ADD SEARCH OPTIMIZATION

为整个事件表添加搜索优化，如果指定了可选 ON 子句，则为特定列添加。

注意：

搜索优化的维护成本可能很高，尤其是在事件表中的数据频繁更改的情况下。有关更多信息，请参阅搜索优化成本估算和管理。
如果尝试在物化视图上添加搜索优化，Snowflake 将返回错误消息。

ON search_method_with_target [, search_method_with_target ... ]

指定要为特定列或 VARIANT 字段（而不是整个事件表）配置搜索优化。

对于 search_method_with_target，请使用具有以下语法的表达式：

<search_method>(<target> [, ...])

其中：

search_method 指定下列方法之一，用于优化特定类型的谓词的查询：


搜索方式	描述
`EQUALITY`	等式和 IN 谓词。
`SUBSTRING`	匹配子字符串和正则表达式的谓词（例如 [ NOT ] LIKE、[ NOT ] ILIKE、[ NOT ] RLIKE、REGEXP_LIKE 等）
`GEO`	使用 GEOGRAPHY 类型的谓词。

target 指定列、VARIANT 字段或星号 (*)。

根据 search_method 的值，可以指定以下类型之一的列或 VARIANT 字段：


搜索方式	支持的目标
`EQUALITY`	数值、字符串、二进制和 VARIANT 数据类型的列，包括 VARIANTs 中的字段的路径。要指定 VARIANT 字段，请使用冒号分隔的字段路径（例如 `my_column:my_field_name:my_nested_field_name`），或使用 :ref:` 点或括号表示法 <label-traversing_semistructured_data>` （例如 `my_column:my_field_name.my_nested_field_name` 或 `my_column['my_field_name']['my_nested_field_name']`）。指定 VARIANT 字段时，该配置将应用于该字段下的所有嵌套字段。例如，假设您指定 `ON EQUALITY(src:a.b)`：此配置可以改进查询 `on src:a.b` 和任何嵌套字段（例如 `src:a.b.c`、`src:a.b.c.d` 等）。此配置不会影响不使用 `src:a.b` 前缀的查询（例如 `src:a`、`src:z` 等）。
`SUBSTRING`	字符串数据类型的列。
`GEO`	GEOGRAPHY 数据类型的列。

要将事件表中所有适用的列指定为目标，请使用星号 (*)。

请注意，不能为给定的搜索方法同时指定星号和特定列名。但是，您可以在不同的搜索方法中指定星号。

例如，您可以指定以下表达式：

-- Allowed
ON SUBSTRING(*)
ON EQUALITY(*), SUBSTRING(*), GEO(*)

不能指定以下表达式：

-- Not allowed
ON EQUALITY(*, c1)
ON EQUALITY(c1, *)
ON EQUALITY(v1:path, *)
ON EQUALITY(c1), EQUALITY(*)

若要在目标上指定多个搜索方法，请使用逗号分隔每个后续方法和目标：

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

如果您在同一事件表上多次运行 ALTER TABLE ...ADD SEARCH OPTIMIZATION ON ... 命令，则每个后续命令都会添加到事件表的现有配置中。例如，假设您运行以下命令：

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

这会将 c1、c2、c3 和 c4 列的相等谓词添加到事件表的配置中。这相当于运行以下命令：

ALTER TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

有关示例，请参阅为特定列启用搜索优化。

DROP SEARCH OPTIMIZATION

移除整个事件表的搜索优化，或者如果指定了可选 ON 子句，则从特定列中移除。

注意：

如果事件表具有搜索优化属性，则删除事件表并取消删除它将保留搜索优化属性。
从事件表中移除搜索优化属性然后重新添加它时，会产生与首次添加搜索优化属性时相同的成本。

ON search_method_with_target | column_name | expression_id [, ... ]

指定要为特定列或 VARIANT 字段（而不是删除整个事件表的搜索优化）删除搜索优化配置。

若要标识要删除的列配置，请指定以下配置之一：

对于 search_method_with_target，指定一种方法，用于优化一个或多个特定目标（可以是列或 VARIANT 字段）的查询。使用前面描述的语法。
对于 column_name，指定为搜索优化配置的列的名称。指定列名称将删除该列的所有表达式，包括使用列中 VARIANT 字段的表达式。
对于 expression_id，指定 DESCRIBE SEARCH OPTIMIZATION 命令的输出中列出的表达式 ID。

若要指定其中的多个项，请在项之间使用逗号分隔。

可以指定具有目标、列名和表达式 IDs 的搜索方法的任意组合。

有关示例，请参阅删除特定列的搜索优化。

使用说明¶

对事件表的更改不会自动传播到在该事件表上创建的视图。
要更改事件表，您必须使用对事件表具有所有权权限的角色。
若要为事件表添加聚类，还必须具备包含该事件表的架构和数据库的 USAGE 或 OWNERSHIP 权限。

使用行访问策略：
- Snowflake 支持在单个 SQL 语句中添加和删除行访问策略。
  
  例如，若要将已在表上设置的行访问策略替换为其他策略，请先删除行访问策略，然后再添加新的行访问策略。
- 对于给定资源（即表或视图），要 ADD 或 DROP 行访问策略，必须具有架构的 APPLY ROW ACCESS POLICY 权限，或者资源的 OWNERSHIP 权限，以及行访问策略资源的 APPLY 权限。
- 一个表或视图一次只能由一个行访问策略保护。如果策略正文引用受行访问策略保护的表或视图列或受掩码策略保护的列，则添加策略将失败。
  
  同样，如果掩码策略正文引用受行访问策略或其他掩码策略保护的表，则向表列添加掩码策略将失败。
- 行访问策略不能应用于系统视图或表函数。
- 与其他 DROP <object> 操作类似，如果尝试从未添加行访问策略的资源中删除行访问策略，则 Snowflake 会返回错误。
- 如果对象同时具有行访问策略和一个或多个掩码策略，则首先评估行访问策略。

如果创建外键，则 REFERENCES 子句中列的顺序必须与主键中列的顺序相同。例如：
```
CREATE TABLE parent ... CONSTRAINT primary_key_1 PRIMARY KEY (c_1, c_2) ...
CREATE TABLE child  ... CONSTRAINT foreign_key_1 FOREIGN KEY (...) REFERENCES parent (c_1, c_2) ...
```
在这两种情况下，列的顺序均为 c_1, c_2。如果外键中列的顺序不同（例如 c_2, c_1），则创建外键的尝试将失败。

您可以通过执行 ALTER TABLE 命令来对事件表使用数据指标函数。有关更多信息，请参阅使用 SQL 设置数据指标函数。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。
ALTER TABLE ... CHANGE_TRACKING = TRUE
- 当更改事件表以启用更改跟踪时，事件表将在操作期间锁定。锁定可能会导致某些关联的 DDL/DML 操作出现延迟。有关更多信息，请参阅资源锁定。

示例¶

将事件表 t1 重命名为 a1：

CREATE OR REPLACE TABLE t1(a1 number);

SHOW TABLES LIKE 't1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | T1   | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+

ALTER TABLE t1 RENAME TO tt1;

SHOW TABLES LIKE 'tt1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | TT1  | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+

更改事件表的群集密钥顺序：

CREATE OR REPLACE TABLE T1 (id NUMBER, date TIMESTAMP_NTZ, name STRING) CLUSTER BY (id, date);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (ID,DATE)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

-- Change the order of the clustering key
ALTER TABLE t1 CLUSTER BY (date, id);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (DATE,ID)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

下面的示例在指定单个列时对事件表添加行访问策略。设置策略后，可以通过检查 Information Schema 进行验证。

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_t1 ON (empl_id);

下面的示例在单个事件表中指定两列时添加行访问策略。

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_test2 ON (cost, item);

以下示例从事件表中删除行访问策略。通过查询 Information Schema 来验证策略是否已删除。

ALTER TABLE t1
  DROP ROW ACCESS POLICY rap_v1;

以下示例演示如何在表的单个 SQL 语句中合并添加和删除行访问策略。通过检查 Information Schema 来验证结果。

alter table t1
  drop row access policy rap_t1_version_1,
  add row access policy rap_t1_version_2 on (empl_id);

ALTER TABLE（事件表）¶

语法¶

参数¶

数据治理策略和标签操作 (dataGovnPolicyTagAction)¶

群集操作 (clusteringAction)¶

搜索优化操作 (searchOptimizationAction)¶

使用说明¶

示例¶

数据治理策略和标签操作 (`dataGovnPolicyTagAction`)¶

群集操作 (`clusteringAction`)¶

搜索优化操作 (`searchOptimizationAction`)¶