ALTER DYNAMIC TABLE¶

修改 :doc:` 动态表 </user-guide/dynamic-tables-about>` 的属性。

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

本主题内容：

语法¶

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> { SUSPEND | RESUME }

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> SWAP WITH <target_dynamic_table_name>

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> REFRESH [ COPY SESSION ]

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> { clusteringAction }

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> { tableColumnCommentAction }

ALTER DYNAMIC TABLE <name> { SET | UNSET } COMMENT = '<string_literal>'

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> dataGovnPolicyTagAction

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> searchOptimizationAction

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> SET
  [ TARGET_LAG = { '<num> { seconds | minutes | hours | days }'  | DOWNSTREAM } ]
  [ WAREHOUSE = <warehouse_name> ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
  [ LOG_LEVEL = '<log_level>' ]
  [ CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]
  [ IMMUTABLE WHERE ( <expr> ) ]

ALTER DYNAMIC TABLE [ IF EXISTS ] <name> UNSET
  [ DATA_RETENTION_TIME_IN_DAYS ],
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS ],
  [ DEFAULT_DDL_COLLATION ]
  [ LOG_LEVEL ]
  [ CONTACT <purpose> ]
  [ IMMUTABLE ]

Copy

其中：

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

Copy

有关更多信息，请参阅群集密钥和聚类表。

tableCommentAction ::=
  {
    ALTER | MODIFY [ ( ]
                           [ COLUMN ] <col1_name> COMMENT '<string>'
                         , [ COLUMN ] <col1_name> UNSET COMMENT
                       [ , ... ]
                   [ ) ]
  }

Copy

dataGovnPolicyTagAction ::=
  {
      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
  }
  |
  {
    SET AGGREGATION POLICY <policy_name>
      [ ENTITY KEY ( <col_name> [, ... ] ) ]
      [ FORCE ]
  | UNSET AGGREGATION POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
}
|
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                  , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }

Copy

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

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

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

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

Copy

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

参数¶

name

要更改的动态表的标识符。

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

有关更多信息，请参阅标识符要求。

SUSPEND | RESUME

指定要对动态表执行的操作：

SUSPEND 会暂停动态表上的刷新。如果一个动态表被其他动态表使用，它们也会被暂停。
RESUME 会恢复动态表上的刷新。恢复操作向下游级联到所有未手动暂停的下游动态表。

RENAME TO new_name

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

重命名动态表需要动态表架构的 CREATE DYNAMIC TABLE 权限。

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

以下限制条件适用：

目标数据库和/或架构必须已存在。此外，新位置中不能存在同名对象；否则，该语句将返回错误。
除非对象所有者（即对对象拥有 OWNERSHIP 权限的角色）也拥有目标架构，否则不得将对象移动到托管访问架构。
重命名对象（表、列等）时，引用该对象的其他对象必须使用新名称进行更新。

SWAP WITH target_dynamic_table_name

在单个事务中交换两个动态表。用于执行此操作的角色必须对两个动态表都具有 OWNERSHIP 权限。

以下限制条件适用：

只能将一个动态表与另一个动态表交换。

REFRESH [ COPY SESSION ]

指定应手动刷新动态表。

由用户暂停和自动暂停的动态表均可手动刷新。手动刷新的动态表会返回 MANUAL 作为DYNAMIC_TABLE_REFRESH_HISTORY 函数中 refresh_trigger 的输出。

请注意，刷新动态表也会刷新截至同一数据时间戳的所有上游动态表。有关更多信息，请参阅更改动态表的仓库或目标滞后。

有关动态表刷新状态的信息，请参阅 DYNAMIC_TABLE_REFRESH_HISTORY。

COPY SESSION

使用当前用户和仓库在当前会话的副本中运行刷新操作。

这仅适用于一次手动刷新；它不会永久更新动态表的凭据。使用 GRANT OWNERSHIP 命令转移计划刷新的所有权。有关更多信息，请参阅转移所有权。

主要角色是拥有动态表的角色，次要角色将匹配用户的 DEFAULT_SECONDARY_ROLES 属性。

SET ...

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

TARGET_LAG = { num { seconds | minutes | hours | days } | DOWNSTREAM }

为动态表指定目标滞后时间：

'num seconds | minutes | hours | days'

指定动态表内容滞后于基表更新的最长时间。

例如：

如果动态表中数据的滞后时间不超过 5 分钟，请指定 5 minutes。
如果动态表中数据的滞后时间不超过 5 小时，请指定 5 hours。

最小值为 1 分钟。如果动态表 A 依赖于另一个动态表 B，则 A 的最小滞后时间必须大于或等于 B 的滞后时间。

DOWNSTREAM

指定在动态表的任何下游动态表被刷新时，应该刷新动态表。

WAREHOUSE = warehouse_name

指定提供计算资源以刷新动态表的仓库的名称。

动态表的所有者角色必须拥有该仓库的 USAGE 权限。

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。

DEFAULT_DDL_COLLATION = 'collation_specification'

为添加到动态表中的任何新列指定默认排序规则规范。

设置该参数不会更改任何现有列的排序规则规范。

有关更多信息，请参阅 DEFAULT_DDL_COLLATION。

LOG_LEVEL = 'log_level'

指定此动态表的事件的严重级别，这些事件被引入并在活动事件表中可用。引入指定级别（以及更严重级别）的事件。

有关级别的更多信息，请参阅 LOG_LEVEL。有关设置日志级别的信息，请参阅为日志、指标和跟踪设置级别。

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

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

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

IMMUTABLE WHERE: 指定一个条件来定义动态表的不可变部分。有关更多信息，请参阅使用不可变性约束创建动态表。

UNSET ...

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

DATA_RETENTION_TIME_IN_DAYS
MAX_DATA_EXTENSION_TIME_IN_DAYS
DEFAULT_DDL_COLLATION
LOG_LEVEL
CONTACT purposes
IMMUTABLE

群集操作 (`clusteringAction`)¶

CLUSTER BY ( expr [ , expr , ... ] )

指定（或修改）一个或多个表列或列表达式作为动态表的群集密钥。这些是自动聚类维护聚类的列/表达式。在为动态表指定群集密钥之前，应当对微分区有所了解。有关更多信息，请参阅了解 Snowflake 表结构。

将群集密钥与动态表一起使用时请注意以下几点：

列定义是必需的，必须在语句中明确指定。
群集密钥并非旨在或建议用于所有表；它们通常有利于非常大（例如多 TB）的表。

SUSPEND | RESUME RECLUSTER

启用或禁用动态表的自动聚类。

DROP CLUSTERING KEY

删除动态表的群集密钥。

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

表注释操作 (`tableCommentAction`)¶

ALTER | MODIFY [ ( ] . [ COLUMN ] <col1_name> COMMENT '<string>' . , [ COLUMN ] <col1_name> UNSET COMMENT . [ , ... ] . [ ) ]: 更改动态表中列的注释或覆盖现有注释。
SET | UNSET COMMENT = '<string_literal>': 添加注释或覆盖动态表的现有注释。

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

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

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

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

有关在语句中指定标签的信息，请参阅对象的标签配额。

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

Drops all row access policy associations from the dynamic table.

You must also use this clause to access a dynamic table that you restore from a snapshot, if a row access policy applied to the table when the snapshot was created and the policy was later dropped. After the dynamic table is restored, you can't query it until you run an ALTER TABLE command with the DROP ALL ROW ACCESS POLICIES clause.

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

指定要传递到条件掩码策略的实参。

列表中的第一列指定要根据策略条件进行掩码或令牌化处理的数据，并且必须与应用掩码策略的列相匹配。

附加列指定了当从第一列中进行选择时，要在查询结果的每一行中评估哪些数据以进行掩码或令牌化处理。

如果省略 USING 子句，Snowflake 会将条件掩码策略视为正常的掩码策略。

SET AGGREGATION POLICY {policy_name}

[ ENTITY KEY ({col_name} [ , ... ]) ] [ FORCE ]

为动态表分配聚合策略。

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

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

UNSET AGGREGATION POLICY

从动态表中分离聚合策略。

FORCE

在单个语句中将当前为列设置的掩码或投影策略替换为其他策略。

请注意，将 FORCE 关键字与掩码策略配合使用要求 ALTER DYNAMIC TABLE 语句中策略的 :doc:`数据类型 </sql-reference-data-types>`（即 STRING）与当前在该列上设置的掩码策略的数据类型（即 STRING）相匹配。

如果当前没有为该列设置掩码策略，则指定此关键字无效。

有关详细信息，请参阅：替换列上的掩码策略或替换投影策略。

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

ADD SEARCH OPTIMIZATION

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

搜索优化的维护成本可能很高，尤其是在表中的数据频繁更改的情况下。有关更多信息，请参阅搜索优化成本估算和管理。

ON search_method_with_target [, search_method_with_target ... ]

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

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

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

Copy

其中：

search_method 指定下列方法之一，用于优化特定类型的谓词的查询：
- GEO：使用 GEOGRAPHY 类型的谓词。
- SUBSTRING：匹配子字符串和正则表达式的谓词（例如 [ NOT ] LIKE、[ NOT ] ILIKE、[ NOT ] RLIKE、REGEXP_LIKE 等）
- EQUALITY：等式和 IN 谓词。
target 指定列、VARIANT 字段或星号 (*)。

根据 search_method 的值，可以指定以下类型之一的列或 VARIANT 字段：
- GEO：GEOGRAPHY 数据类型的列。
- SUBSTRING：字符串或 VARIANT 数据类型的列，包括 VARIANTs 中的字段的路径。指定字段的路径，如 EQUALITY 所述；以相同的方式改进对嵌套字段的搜索。
- EQUALITY：数值、字符串、二进制和 VARIANT 数据类型的列，包括 VARIANT 列中的字段的路径。
  
  要指定 VARIANT 字段，请使用 :ref:` 点或括号表示法 <label-traversing_semistructured_data>`。例如：
  - my_column:my_field_name.my_nested_field_name
  - 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 等）。

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

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

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

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

Copy

不能指定以下表达式：

ON EQUALITY(*, c1)
ON EQUALITY(c1, *)
ON EQUALITY(v1:path, *)
ON EQUALITY(c1), EQUALITY(*)

Copy

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

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

Copy

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

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

Copy

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

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

Copy

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

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 的搜索方法的任意组合。

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

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：

权限	对象	备注
OWNERSHIP 或 OPERATE	您要修改的动态表。	只有拥有 OWNERSHIP 权限时，某些操作才受支持。有关更多信息，请参阅更改动态表的权限。

The USAGE privilege on the parent database and schema are required to perform operations on any object in a schema. Note that a role granted any privilege on a schema allows that role to resolve the schema. For example, a role granted CREATE privilege on a schema can create objects on that schema without also having USAGE granted on that schema.

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

要更改动态表，您必须使用对该动态表具有 OPERATE 权限的角色。有关一般信息，请参阅查看动态表元数据的权限。
更改基表上掩码策略会导致重新初始化。
如果要更新现有动态表，并需要查看其当前定义，请调用 GET_DDL 函数。
您可以通过执行 ALTER TABLE 命令来对动态表使用数据指标函数。有关更多信息，请参阅使用数据指标函数执行数据质量检查。
不能使用 IDENTIFIER() 来指定要更改的动态表的名称。例如，不支持以下语句：
```
ALTER DYNAMIC TABLE IDENTIFIER(my_dynamic_table) SUSPEND;
```
Copy
重新初始化或完全刷新后，将重建动态表的搜索索引。此过程包括删除现有索引并从头开始重建它们，这可能会产生较高的成本。有关更多信息，请参阅搜索优化成本估算和管理。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例¶

将名为 my_dynamic_table 的动态表的目标滞后时间更改为 1 小时：

ALTER DYNAMIC TABLE my_dynamic_table SET
  TARGET_LAG = '1 hour';

Copy

为 my_dynamic_table 指定下游目标延迟：

ALTER DYNAMIC TABLE my_dynamic_table SET TARGET_LAG = DOWNSTREAM;

Copy

暂停动态表：

ALTER DYNAMIC TABLE my_dynamic_table SUSPEND;

Copy

恢复动态表：

ALTER DYNAMIC TABLE my_dynamic_table RESUME;

Copy

重命名 my_dynamic_table：

ALTER DYNAMIC TABLE my_dynamic_table RENAME TO my_updated_dynamic_table;

Copy

交换 my_dynamic_table 与 my_new_dynamic_table：

ALTER DYNAMIC TABLE my_dynamic_table SWAP WITH my_new_dynamic_table;

Copy

更改动态表的群集密钥：

ALTER DYNAMIC TABLE my_dynamic_table CLUSTER BY (date);

Copy

从动态表中移除群集：

ALTER DYNAMIC TABLE my_dynamic_table DROP CLUSTERING KEY;

Copy

使用当前会话中的用户、次要角色和仓库设置手动刷新 my_dynamic_table。这可确保刷新操作在用户会话的确切上下文中运行。

ALTER DYNAMIC TABLE my_dynamic_table REFRESH COPY SESSION

Copy

ALTER DYNAMIC TABLE¶

语法¶

参数¶

群集操作 (clusteringAction)¶

表注释操作 (tableCommentAction)¶

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

搜索优化操作 (searchOptimizationAction)¶

访问控制要求¶

使用说明¶

示例¶

群集操作 (`clusteringAction`)¶

表注释操作 (`tableCommentAction`)¶

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

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