CREATE DYNAMIC TABLE¶

根据指定的查询创建动态表。

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

本主题内容：

语法¶

CREATE [ OR REPLACE ] [ TRANSIENT ] DYNAMIC TABLE [ IF NOT EXISTS ] <name> (
    -- Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]

  )
  TARGET_LAG = { '<num> { seconds | minutes | hours | days }' | DOWNSTREAM }
  WAREHOUSE = <warehouse_name>
  [ REFRESH_MODE = { AUTO | FULL | INCREMENTAL } ]
  [ INITIALIZE = { ON_CREATE | ON_SCHEDULE } ]
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  AS <query>

Copy

变体语法¶

CREATE DYNAMIC TABLE ... CLONE¶

创建具有相同的列定义的新动态表，并包含源动态表中的全部现有数据，而不会实际复制数据。此变体还可用于克隆过去特定时间点的动态表。请参阅克隆注意事项。

CREATE [ OR REPLACE ] [ TRANSIENT ] DYNAMIC TABLE <name>
  CLONE <source_dynamic_table>
        [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
  [
    COPY GRANTS
    TARGET_LAG = { '<num> { seconds | minutes | hours | days }' | DOWNSTREAM }
    WAREHOUSE = <warehouse_name>
  ]

Copy

如果源动态表具有群集密钥，则克隆的动态表具有群集密钥。默认情况下，即使来源表的自动聚类未暂停，新表的自动聚类也会暂停。

有关克隆的更多详细信息，请参阅 CREATE <object> ... CLONE。

必填参数¶

name

指定动态表的标识符（即名称）；对于在其中创建动态表的架构必须唯一。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

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

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 权限才能创建动态表。

AS query

指定动态表应包含其结果的查询。

可选参数¶

TRANSIENT

指定表为瞬态。

与永久动态表一样，瞬态动态表在显式删除之前一直存在，任何具有相应权限的用户都可以使用。瞬态动态表不会将数据保留在故障安全存储中，这有助于降低存储成本，特别是对于频繁刷新的表。由于耐用性降低，瞬态动态表最适合存储瞬态数据，即不需要永久表所提供的相同级别的数据保护和恢复的数据。

默认：无值。如果动态表未声明为 TRANSIENT，则该表为永久表。

REFRESH_MODE = { AUTO | FULL | INCREMENTAL }

为动态表指定刷新模式。创建动态表后无法更改此属性。要修改属性，请使用 CREATE OR REPLACE DYNAMIC TABLE 命令复制动态表。

AUTO
默认情况下强制动态表的增量刷新。如果 CREATE DYNAMIC TABLE 语句不支持增量刷新模式，则自动以完全刷新模式创建动态表。

您可以使用 SHOW DYNAMIC TABLES 语句验证刷新模式。refresh_mode 列显示正在使用的刷新模式，而 text 列显示用户指定的刷新模式。

备注

启用 2024_04 行为变更捆绑包后，Snowflake 会根据您的查询定义选择可能表现最佳的刷新模式。要确定适合您用例的最佳模式，请尝试不同的刷新模式和自动建议。要在不同的 Snowflake 版本中保持一致的行为，您应该在所有动态表上显式设置刷新模式。

FULL
强制动态表完全刷新，即使动态表可以增量刷新。

INCREMENTAL
强制动态表的增量刷新。如果作为动态表基础的查询无法执行增量刷新，则动态表创建失败并显示错误消息。

默认：AUTO

INITIALIZE

指定动态表的初始刷新的行为。创建动态表后无法更改此属性。要修改属性，请使用 CREATE OR REPLACE DYNAMIC TABLE 命令替换动态表。

ON_CREATE
创建时同步刷新动态表。如果此刷新失败，则动态表创建失败并显示错误消息。

ON_SCHEDULE
在下次计划刷新时刷新动态表。

刷新计划过程运行时将填充动态表。创建动态表时不填充数据。如果您尝试使用 SELECT * FROM DYNAMIC TABLE 查询表，可能会看到以下错误，因为第一次计划刷新尚未发生。
Dynamic Table is not initialized. Please run a manual refresh or wait for a scheduled refresh before querying.
默认：ON_CREATE

COMMENT 'string_literal'

指定列的注释。

（请注意，可以在列级别或表级别指定注释。相应的语法略有不同。

MASKING POLICY = policy_name

指定要在列上设置的掩码策略。

column_list

如果您希望在动态表中更改列的名称或向列添加注释，请包含一个列列表，该列表指定列名和（如果需要）关于列的注释。无需指定列的数据类型。

如果动态表中的任何列都基于表达式（例如，不仅是简单的列名），则必须为动态表中的每个列提供列名。例如，在以下情况下，列名是必需的：

CREATE DYNAMIC TABLE product (pre_tax_profit, taxes, after_tax_profit)
  TARGET_LAG = '20 minutes'
    WAREHOUSE = mywh
    AS
      SELECT revenue - cost, (revenue - cost) * tax_rate, (revenue - cost) * (1.0 - tax_rate)
      FROM staging_table;

Copy

您可以为每列指定可选注释。例如：

CREATE DYNAMIC TABLE product (pre_tax_profit COMMENT 'revenue minus cost',
                taxes COMMENT 'assumes taxes are a fixed percentage of profit',
                after_tax_profit)
  TARGET_LAG = '20 minutes'
    WAREHOUSE = mywh
    AS
      SELECT revenue - cost, (revenue - cost) * tax_rate, (revenue - cost) * (1.0 - tax_rate)
      FROM staging_table;

Copy

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

将动态表中的一个或多个列或列表达式指定为群集密钥。在为动态表指定群集密钥之前，应当对微分区有所了解。有关更多信息，请参阅了解 Snowflake 表结构。

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

列定义是必需的，必须在语句中明确指定。
默认情况下，即使来源表的自动聚类已暂停，新动态表的自动聚类也不会暂停。
群集密钥并非旨在或建议用于所有表；它们通常有利于非常大（例如多 TB）的表。
指定 CLUSTER BY 不会在创建时对数据进行聚类；相反，CLUSTER BY 依赖于自动聚类来随着时间的推移重聚类数据。

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

默认：无值（未为表定义群集密钥）

DATA_RETENTION_TIME_IN_DAYS = integer

指定动态表的保留期，以便可以对动态表中的历史数据执行 Time Travel 操作（SELECT、CLONE）。Time Travel 对动态表的行为与对传统表的行为相同。有关更多详细信息，请参阅了解和使用 Time Travel。

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

值：

Standard Edition：0 或 1
Enterprise Edition：
- 0 至 90 用于永久表
- 0 或 1 临时表和瞬态表

默认：

Standard Edition：1
Enterprise Edition（或更高版本）：1 （除非在架构、数据库或账户级别指定了不同的默认值）

备注

0 值实际上会为表禁用 Time Travel。

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

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

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

COMMENT = 'string_literal'

指定动态表的注释。

（请注意，可以在列级别或表级别指定注释。相应的语法略有不同。

默认：无值。

COPY GRANTS

指定在使用 CREATE DYNAMIC TABLE ...CLONE 变体创建新动态表时保留原始动态表的访问权限。

此参数将除 OWNERSHIP 之外的所有权限从现有动态表复制到新动态表。新动态表不会继承为架构中的对象类型定义的任何未来授权。默认情况下，执行 CREATE DYNAMIC TABLE 语句的角色拥有新动态表。

如果该参数未包含在 CREATE DYNAMIC TABLE 语句中，则新表不会继承在原始动态表上授予的任何显式访问权限，但会继承为架构中的对象类型定义的任何未来授权。

注意：

借助数据共享：
- 如果现有动态表已共享到另一个账户，则替换动态表也会共享。
- 如果现有动态表已作为数据使用者与您的账户共享，并且进一步授予了对账户中其他角色的访问权限（在父数据库上使用 GRANT IMPORTED PRIVILEGES），则还会授予对替换动态表的访问权限。
替换动态表的 SHOW GRANTS 输出会将复制权限的获得者列为执行 CREATE TABLE 语句的角色，并附带执行语句时的当前时间戳。
替换动态表的 SHOW GRANTS 输出会将复制权限的获得者列为执行 CREATE TABLE 语句的角色，并附带执行语句时的当前时间戳。
复制授权的操作在 CREATE DYNAMIC TABLE 命令中会以原子方式发生（即在同一事务中）。

ROW ACCESS POLICY policy_name ON ( col_name [ , col_name ... ] )

指定要在动态表上设置的行访问策略。

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

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

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

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

访问控制要求¶

用于执行此 SQL 命令的角色必须至少具有以下权限：

权限	对象	备注
CREATE DYNAMIC TABLE	计划在其中创建动态表的架构。
SELECT	计划查询新动态表的表、视图和动态表。
USAGE	计划用于刷新表的仓库。

请注意，对架构中的对象进行操作还需要对父数据库和架构具有 USAGE 权限。

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

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

使用说明¶

执行 CREATE DYNAMIC TABLE 命令时，当前正在使用的角色将成为动态表的所有者。此角色用于在后台执行动态表的刷新。
创建动态表后不能对架构进行变更。
动态表会随着基础数据库对象的变更而更新。必须对动态表使用的所有基础对象启用变更跟踪。请参阅启用更改跟踪。
如果要替换现有的动态表并需要查看其当前定义，请调用 GET_DDL 函数。
在动态表的定义中使用 ORDER BY 可能会产生按意外顺序排序的结果。您可以在查询动态表时使用 ORDER BY，以确保所选行按特定顺序返回。
Snowflake 不支持使用 ORDER BY 创建从动态表中选择的视图。

动态表中现在不支持某些表达式、子句和函数。有关完整列表，请参阅动态表的已知限制。
客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例¶

创建名为 product 的动态表：

CREATE OR REPLACE DYNAMIC TABLE product
 TARGET_LAG = '20 minutes'
  WAREHOUSE = mywh
  AS
    SELECT product_id, product_name FROM staging_table;

Copy

在上面的例子中：

动态表可具体化对 staging_table 表的 product_id 列和 product_name 列的查询结果。
目标滞后时间为 20 分钟，这意味着理想情况下，动态表中的数据不应比 staging_table 中的数据早 20 分钟。
自动刷新过程使用仓库 mywh 中的计算资源来刷新动态表中的数据。

使用多列群集密钥来创建表：

CREATE DYNAMIC TABLE product (date TIMESTAMP_NTZ, id NUMBER, content VARIANT)
  TARGET_LAG = '20 minutes'
  WAREHOUSE = mywh
  CLUSTER BY (date, id)
  AS
    SELECT product_id, product_name FROM staging_table;

Copy

克隆在指定时间戳的日期和时间存在的动态表：

CREATE DYNAMIC TABLE product_clone CLONE product AT (TIMESTAMP => TO_TIMESTAMP_TZ('04/05/2013 01:02:03', 'mm/dd/yyyy hh24:mi:ss'));

Copy