CREATE DATABASE¶

语法¶

标准数据库

CREATE [ OR REPLACE ] [ TRANSIENT ] DATABASE [ IF NOT EXISTS ] <name>
    [ CLONE <source_schema>
        [ { AT | BEFORE } ( { TIMESTAMP => <timestamp> | OFFSET => <time_difference> | STATEMENT => <id> } ) ]
        [ IGNORE TABLES WITH INSUFFICIENT DATA RETENTION ]
        [ IGNORE HYBRID TABLES ] ]
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
    [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
    [ EXTERNAL_VOLUME = <external_volume_name> ]
    [ CATALOG = <catalog_integration_name> ]
    [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
    [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
    [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
    [ COMMENT = '<string_literal>' ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

标准数据库（来自列表）

CREATE DATABASE <name> FROM LISTING '<listing_global_name>'

共享数据库（来自共享）

CREATE DATABASE <name> FROM SHARE <provider_account>.<share_name>

辅助数据库 (Database Replication)

CREATE DATABASE <name>
    AS REPLICA OF <account_identifier>.<primary_db_name>
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]

变体语法¶

CREATE OR ALTER [ TRANSIENT ] DATABASE <name>
    [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
    [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
    [ EXTERNAL_VOLUME = <external_volume_name> ]
    [ CATALOG = <catalog_integration_name> ]
    [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
    [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
    [ LOG_LEVEL = '<log_level>' ]
    [ TRACE_LEVEL = '<trace_level>' ]
    [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
    [ COMMENT = '<string_literal>' ]

必填参数¶

name

指定数据库的标识符；对于您的账户必须是唯一的。

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

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

重要

作为 :doc:` Database Replication 和故障转移 </user-guide/db-replication-intro>` 的最佳实践，我们建议为每个辅助数据库提供与其主数据库相同的名称。此实践支持同一数据库中的其他对象引用完全限定对象（即 :code:` '<db>.<schema>.<object>' `），例如在视图中查询完全限定表名。

如果辅助数据库的名称与主数据库的名称不同，则这些对象引用将在辅助数据库中中断。

可选参数¶

TRANSIENT

将数据库指定为瞬态的。瞬态数据库没有故障安全期，因此一旦它们离开 Time Travel，它们就不会产生额外的存储成本；但是，这意味着它们在数据丢失时也不会受故障安全的保护。有关更多信息，请参阅 了解和查看故障安全。

此外，根据定义，在瞬态数据库中创建的所有架构（以及所有表）都是瞬态的。有关瞬态表的更多信息，请参阅 CREATE TABLE。

默认：无值（即数据库是永久性的）

CLONE source_db

指定创建指定的源数据库的克隆。有关克隆数据库的更多详细信息，请参阅 CREATE <object> ...CLONE。

AT | BEFORE ( TIMESTAMP => timestamp | OFFSET => time_difference | STATEMENT => id )

克隆一个数据库时，AT | BEFORE 子句指定使用 Time Travel 在过去特定时间点或之前克隆该数据库。如果指定的 Time Travel 时间等于或早于数据库创建的时间点，则克隆操作将失败并出现错误。

IGNORE TABLES WITH INSUFFICIENT DATA RETENTION

功能支持的区域

此功能在中华人民共和国不可用。

忽略在 Time Travel 中不再具有可供克隆的历史数据的表。如果 AT | BEFORE 子句中指定的过去时间超出了数据库或架构中任何子表的数据保留期，则跳过子表的克隆操作。有关更多信息，请参阅 子对象和数据保留时间。

IGNORE HYBRID TABLES

忽略混合表，不会克隆这些表。使用该选项克隆包含混合表的数据库。克隆的数据库包括其他对象，但会跳过混合表。

如果您不使用此选项，且您的数据库包含一个或多个混合表，该命令将静默忽略混合表。但是，对于包含混合表的数据库的错误处理在即将发布的版本中会发生变化；因此，您可能想要抢先将此参数添加到您的命令中。

DATA_RETENTION_TIME_IN_DAYS = integer

指定可以对数据库执行 Time Travel 操作（CLONE 和 UNDROP）的天数，并指定在数据库中创建的所有架构的默认 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。

EXTERNAL_VOLUME = external_volume_name

对象参数，指定要用于 Apache Iceberg™ 表 的默认外部卷。

有关此参数的详细信息，请参阅 EXTERNAL_VOLUME。

CATALOG = catalog_integration_name

对象参数，指定要用于 Apache Iceberg™ 表 的默认目录集成。

有关此参数的详细信息，请参阅 CATALOG。

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

指定在 Iceberg 表 的查询结果中是否使用 Unicode 替换字符 (�) 替换无效的 UTF-8 字符。您只能为使用外部 Tables 目录的表设置此参数。

• TRUE 会将无效的 UTF-8 字符替换为 Unicode 替换字符。

• FALSE 保留无效的 UTF-8 字符不变。如果在 Parquet 数据文件中遇到无效的 UTF-8 字符，Snowflake 会返回用户错误消息。

默认：FALSE

DEFAULT_DDL_COLLATION = 'collation_specification'

为添加到数据库的所有架构和表指定默认 排序规则规范。可以在架构和单个表级别上覆盖默认值。

有关该参数的更多详细信息，请参阅 DEFAULT_DDL_COLLATION。

LOG_LEVEL = 'log_level'

指定应引入并在活动事件表中可用的消息的严重级别。引入指定级别（以及更严重级别）的消息。

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

TRACE_LEVEL = 'trace_level'

控制如何将跟踪事件引入到事件表中。

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

STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED }

为使用 Snowflake 作为目录的 Apache Iceberg™ 表 指定存储序列化策略。

• COMPATIBLE：Snowflake 对数据文件执行编码和压缩，可确保与第三方计算引擎的互操作性。

• OPTIMIZED：Snowflake 对数据文件执行编码和压缩，可确保 Snowflake 中的最佳表性能。

默认：OPTIMIZED

COMMENT = 'string_literal'

指定数据库的注释。

默认：无值

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

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

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

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

访问控制要求¶

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

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

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

一般使用说明¶

• 创建数据库会自动将其设置为当前会话的活动/当前数据库（相当于使用数据库的 USE DATABASE 命令）。

• 如果已存在同名数据库，则返回错误并且不会创建数据库，除非命令中指定了可选的 OR REPLACE 关键字。

  重要

  使用 OR REPLACE 相当于对现有数据库使用 DROP DATABASE，然后创建一个同名的新数据库；但是，删除的数据库 不会 从系统中永久移除。相反，它保留在 Time Travel 中。这很重要，因为 Time Travel 中删除的数据库有助于账户的数据存储。有关更多信息，请参阅 Time Travel 和故障安全的存储成本。

• CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

• 创建新数据库会自动在数据库中创建两个架构：

  • PUBLIC：数据库的默认架构。

  • INFORMATION_SCHEMA：包含视图和表函数的架构，可用于查询有关数据库中的对象以及账户中的所有对象的元数据。

• 从共享创建的数据库与标准数据库在以下方面有所不同：

  • 它们没有 PUBLIC 或 INFORMATION_SCHEMA 架构，除非这些架构已显式授予共享。

  • 它们无法被克隆。

  • 请勿应用 TRANSIENT 和 DATA_RETENTION_TIME_IN_DAYS 等属性。

• 当数据库处于活动/当前状态时，PUBLIC 架构也默认处于活动/当前状态，除非使用不同的架构或已删除 PUBLIC 架构。

• 关于元数据：

  注意

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

CREATE OR ALTER DATABASE 使用说明¶

• ALTER DATABASE 命令的所有限制均适用。

• 该命令支持 CREATE DATABASE 和 ALTER DATABASE 命令之间重叠的属性和语法。因此，不 支持以下操作：

  • 使用 SWAP WITH 参数交换数据库。

  • 使用 RENAME TO 参数重命名数据库。

  • 使用 CLONE 参数创建数据库的克隆。

  • 添加或更改标签和策略。任何现有标签和策略都会得到保留。

  • 将 TRANSIENT 数据库转换为非 TRANSIENT 数据库，反之亦然。

  • 使用以下命令从共享创建数据库：CREATE OR ALTER DATABASE ...FROM SHARE。

  • 使用以下命令创建辅助（副本）数据库：CREATE OR ALTER DATABASE ...AS REPLICA OF。

Database Replication 使用说明¶

• 数据库复制使用 Snowflake 提供的计算资源（而不是您自己的虚拟仓库）来复制对象和数据。但是，STATEMENT_TIMEOUT_IN_SECONDS 会话/对象参数仍控制语句在取消之前运行的时间。默认值为 ``172800``（2 天）。由于主数据库的 初始复制 可能需要 2 天以上的时间才能完成（具体取决于数据库中的元数据量以及数据库对象中的数据量），因此建议将运行复制操作的会话的 STATEMENT_TIMEOUT_IN_SECONDS 值增加到 ``604800``（7 天，最大值）。

  在同一会话中执行 ALTER DATABASE secondary_db_name REFRESH 语句之前，请运行以下 ALTER SESSION 语句：

  ALTER SESSION SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  请注意，STATEMENT_TIMEOUT_IN_SECONDS 参数也适用于会话中的活动仓库。该参数遵循在会话或仓库级别设置的 较低 值。如果当前会话中有一个处于活动状态的仓库，也请将此仓库的 STATEMENT_TIMEOUT_IN_SECONDS 设置为 604800 （使用 ALTER WAREHOUSE）。

  例如：

  -- determine the active warehouse in the current session (if any)
  SELECT CURRENT_WAREHOUSE();
  
  +---------------------+
  | CURRENT_WAREHOUSE() |
  |---------------------|
  | MY_WH               |
  +---------------------+
  
  -- change the STATEMENT_TIMEOUT_IN_SECONDS value for the active warehouse
  
  ALTER WAREHOUSE my_wh SET STATEMENT_TIMEOUT_IN_SECONDS = 604800;
  

  Copy

  复制操作完成后，您可以将参数值重置为默认值：

  ALTER WAREHOUSE my_wh UNSET STATEMENT_TIMEOUT_IN_SECONDS;
  

  Copy

• 识别存储主数据库的账户的首选方法是使用组织名称和账户名称作为账户标识符。如果您决定改用旧版账户定位器，请参阅 用于复制和故障转移的账户标识符。

• CREATE DATABASE ...AS REPLICA 命令不支持 WITH TAG 子句。

  此子句不受支持，因为辅助数据库是只读的。如果主数据库指定 WITH TAG 子句，请删除该子句以创建辅助数据库。要验证您的数据库是否存在 WITH TAG 子句，请调用 Snowflake 账户中的 GET_DDL 函数并在函数实参中指定主数据库。如果在数据库上设置了标签，则函数输出将包括 ALTER DATABASE ...SET TAG 语句。

  有关更多信息，请参阅 复制和标签。

示例¶

创建两个永久数据库，其中一个数据保留期为 10 天：

CREATE DATABASE mytestdb;

CREATE DATABASE mytestdb2 DATA_RETENTION_TIME_IN_DAYS = 10;

SHOW DATABASES LIKE 'my%';

+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+
| created_on                      | name       | is_default | is_current | origin | owner    | comment | options | retention_time |
|---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB   | N          | N          |        | PUBLIC   |         |         | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2  | N          | N          |        | PUBLIC   |         |         | 10             |
+---------------------------------+------------+------------+------------+--------+----------+---------+---------+----------------+

创建瞬态数据库：

CREATE TRANSIENT DATABASE mytransientdb;

SHOW DATABASES LIKE 'my%';

+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+
| created_on                      | name          | is_default | is_current | origin | owner    | comment | options   | retention_time |
|---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------|
| Tue, 17 Mar 2016 16:57:04 -0700 | MYTESTDB      | N          | N          |        | PUBLIC   |         |           | 1              |
| Tue, 17 Mar 2016 17:06:32 -0700 | MYTESTDB2     | N          | N          |        | PUBLIC   |         |           | 10             |
| Tue, 17 Mar 2015 17:07:51 -0700 | MYTRANSIENTDB | N          | N          |        | PUBLIC   |         | TRANSIENT | 1              |
+---------------------------------+---------------+------------+------------+--------+----------+---------+-----------+----------------+

使用账户 ab67890 提供的共享创建数据库：

CREATE DATABASE snow_sales FROM SHARE ab67890.sales_s;

有关使用共享创建数据库的更多详细示例，请参阅 使用导入的数据。

Database Replication 示例¶

有关创建复制组以将单个数据库复制到目标账户的示例，请参阅 复制单个数据库。

CREATE OR ALTER DATABASE 示例¶

CREATE OR ALTER DATABASE db1;

CREATE OR ALTER DATABASE db1
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

CREATE OR ALTER DATABASE db1
  DEFAULT_DDL_COLLATION = 'de';