CREATE SCHEMA¶

在当前数据库中创建新架构。

该命令支持以下变体：

CREATE OR ALTER SCHEMA：创建架构（如果不存在）或更改现有架构。
CREATE SCHEMA ... CLONE：创建现有架构的克隆，无论是在其当前状态还是在过去的特定时间/点（使用 Time Travel）。有关克隆架构的更多信息，请参阅克隆注意事项。

另请参阅：

ALTER SCHEMA、DESCRIBE SCHEMA、DROP SCHEMA、SHOW SCHEMAS、UNDROP SCHEMA

语法¶

CREATE [ OR REPLACE ] [ TRANSIENT ] SCHEMA [ 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 ] ]
  [ WITH MANAGED ACCESS ]
  [ 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 } ]
  [ CLASSIFICATION_PROFILE = '<classification_profile>' ]
  [ COMMENT = '<string_literal>' ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]
  [ OBJECT_VISIBILITY = PRIVILEGED ]
  [ ENABLE_DATA_COMPACTION = { TRUE | FALSE } ]

Copy

Restored schema (from a snapshot)

CREATE SCHEMA <name> FROM SNAPSHOT SET <snapshot_set> IDENTIFIER '<snapshot_id>'

Copy

变体语法¶

CREATE OR ALTER SCHEMA¶

如果架构尚不存在，则创建一个新架构，或将现有架构转换为语句中定义的架构。CREATE OR ALTER SCHEMA 语句遵循 CREATE SCHEMA 语句的语法规则，并具有与 ALTER SCHEMA 语句相同的限制。

有关更多信息，请参阅 CREATE OR ALTER SCHEMA 使用说明。

CREATE OR ALTER [ TRANSIENT ] SCHEMA <name>
  [ WITH MANAGED ACCESS ]
  [ 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>' ]
  [ OBJECT_VISIBILITY = PRIVILEGED ]

Copy

CREATE SCHEMA ... CLONE¶

创建使用相同参数值的新架构。

CREATE [ OR REPLACE ] SCHEMA [ IF NOT EXISTS ] <name> CLONE <source_schema>
  [ ... ]

Copy

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

必填参数¶

name

指定架构的标识符；对于创建架构的数据库来说必须是唯一的。

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

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

Snapshot parameters¶

The FROM SNAPSHOT SET clause restores a schema from a backup. You don't specify other schema properties because they're all the same as in the backed-up schema.

This form doesn't have a CREATE OR REPLACE clause. You typically either restore the schema under a new name and recover any data or other objects from this new schema, or rename the original schema and then restore the schema under the original name.

备注

The restored schema is independent of the original schema from the snapshot. There isn't any cloning relationship between the restored and original schemas. Therefore, all the micro-partitions for tables in the restored schema are owned by that schema.

If you want to make backups of the newly restored schema, create a new snapshot set for it.

For more information about snapshots, see Snapshots for backups and immutable storage.

snapshot_set: Specifies the name of a snapshot set created for a specific schema. You can use the SHOW SNAPSHOT SETS command to locate the right snapshot set.
snapshot_id: Specifies the identifier of a specific snapshot within that snapshot set. You can use the SHOW SNAPSHOTS IN SNAPSHOT SET command to locate the right identifier within the snapshot set, based on the creation date and time for the snapshot.

可选参数¶

TRANSIENT

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

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

默认：无值（即架构是永久架构）

CLONE source_schema

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

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

克隆一个架构时，AT | BEFORE 子句指定使用 Time Travel 在过去特定时间点或之前克隆该架构。

IGNORE TABLES WITH INSUFFICIENT DATA RETENTION

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

IGNORE HYBRID TABLES

忽略混合表，不会克隆这些表。使用此选项克隆包含混合表的架构。克隆的架构包含其他对象，但会跳过混合表。

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

WITH MANAGED ACCESS

指定托管架构。托管访问架构将权限管理集中到架构所有者。

在常规架构中，对象的所有者（即，具有对象的 OWNERSHIP 权限的角色）可以向其他角色授予对象的进一步权限。在托管架构中，架构所有者管理架构中对对象的所有权限授权，包括未来授权。对象所有者仍然具有对象的 OWNERSHIP 权限；但是，只有架构所有者可以管理对象的权限授予。

DATA_RETENTION_TIME_IN_DAYS = integer

指定可以对架构执行 Time Travel 操作（CLONE 和 UNDROP）的天数，并指定在架构中创建的所有表的默认 Time Travel 保留时间。有关更多详细信息，请参阅了解和使用 Time Travel。

有关此对象级参数的详细说明以及有关对象参数的详细信息，请参阅参数。有关表级保留时间的更多信息，请参阅 CREATE TABLE 和了解和使用 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

CLASSIFICATION_PROFILE = 'classification_profile'

将架构与分类配置文件关联起来，这样架构中的敏感数据就会进行自动分类。

COMMENT = 'string_literal'

指定架构的注释。

默认：无值

CATALOG_SYNC = 'snowflake_open_catalog_integration_name'

指定为 Snowflake Open Catalog 配置的目录集成的名称。如果已指定，Snowflake 会将架构中 Snowflake 管理的 Apache Iceberg™ 表与 Snowflake Open Catalog 账户中的外部目录同步。有关将 Snowflake 管理的 Iceberg 表与 Open Catalog 同步的详细信息，请参阅将 Snowflake 管理的表与 Snowflake Open Catalog 同步。

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

默认：无值

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

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

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

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

WITH CONTACT ( purpose = contact [ , purpose = contact ...] ): 将新对象与一个或多个联系人关联。

OBJECT_VISIBILITY = PRIVILEGED

Specifies the visibility of objects in the account, which controls the discoverability of the objects and enables users without explicit access privileges to find objects and request access. For examples, see 示例.

PRIVILEGED: Specifies that only roles within the current account that are granted an explicit privilege on the object can see the object. This is the default behavior in Snowflake.

For examples, see Make database objects discoverable in Universal Search.

ENABLE_DATA_COMPACTION = { TRUE | FALSE }

Specifies whether Snowflake should enable data compaction on Snowflake-managed Apache Iceberg™ 表.

TRUE: Snowflake performs data compaction on the tables.
FALSE: Snowflake doesn't perform data compaction on the tables.

Default: TRUE

For more information, see ENABLE_DATA_COMPACTION and Set data compaction.

访问控制要求¶

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

权限	对象	备注
CREATE SCHEMA	数据库	可以创建常规访问架构和 :ref:` 托管访问 <label-managed_access_schemas>` 架构。
CREATE SCHEMA ...CLONE ... WITH MANAGED ACCESS	选项	所需的权限取决于源架构是托管架构还是非托管架构：托管：源架构的 OWNERSHIP。非托管：源架构的 MANAGE GRANTS ON ACCOUNT :emph:` 和 ` USAGE。
USAGE	外部卷、目录集成	分别设置 `EXTERNAL_VOLUME` 或 `CATALOG` 对象参数时必需。
MANAGE VISIBILITY	账户	Required to set the OBJECT_VISIBILITY property. Only the SECURITYADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.
MODIFY LOG LEVEL	账户	为架构设置 LOG_LEVEL 时为必需。
MODIFY TRACE LEVEL	账户	为架构设置 TRACE_LEVEL 时为必需。
OWNERSHIP	架构	仅在为现有架构执行 CREATE OR ALTER SCHEMA 语句时需要。 OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

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

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

一般使用说明¶

创建架构会自动将其设置为当前会话的活动/当前架构（相当于使用架构的 USE SCHEMA 命令）。
如果数据库中已存在同名的架构，则返回错误，并且不会创建架构，除非命令中指定了可选的 OR REPLACE 关键字。

重要

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

The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can't both be used in the same statement.
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

在托管访问架构中，架构所有者管理对所包含对象（例如表或视图）的授权，但对这些对象没有其他权限（USAGE、SELECT、DROP 等）。
在目录链接的数据库中，此命令在链接的 Iceberg REST 目录中创建命名空间，并在 Snowflake 数据库中创建相应的架构。对于此用例，Snowflake 仅支持 COMMENT 和 TAG 选项。不支持 CREATE OR ALTER 和 CLONE 变体。
关于元数据：

注意

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

CREATE OR ALTER SCHEMA 使用说明¶

ALTER SCHEMA 命令的所有限制均适用。
此命令不支持以下操作：
- 使用 SWAP WITH 参数交换架构。
- 使用 RENAME TO 参数重命名架构。
- 使用 CLONE 参数创建架构的克隆。
- 添加或更改标签和策略。任何现有标签和策略都会得到保留。
- 将 TRANSIENT 架构转换为非 TRANSIENT 架构，或者反之。

示例¶

创建永久架构：

CREATE SCHEMA myschema;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |         | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |         | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |         | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+---------+----------------+

Copy

创建瞬态架构：

CREATE TRANSIENT SCHEMA tschema;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options   | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |           | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |           | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |           | 1              |
| 2018-12-10 09:35:32.326 -0800 | TSCHEMA            | N          | Y          | MYDB          | PUBLIC       |                                                           | TRANSIENT | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+-----------+----------------+

Copy

创建托管访问架构：

CREATE SCHEMA mschema WITH MANAGED ACCESS;

SHOW SCHEMAS;

+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------+
| created_on                    | name               | is_default | is_current | database_name | owner        | comment                                                   | options        | retention_time |
|-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------|
| 2018-12-10 09:34:02.127 -0800 | INFORMATION_SCHEMA | N          | N          | MYDB          |              | Views describing the contents of schemas in this database |                | 1              |
| 2018-12-10 09:36:47.738 -0800 | MSCHEMA            | N          | Y          | MYDB          | ROLE1        |                                                           | MANAGED ACCESS | 1              |
| 2018-12-10 09:33:56.793 -0800 | MYSCHEMA           | N          | Y          | MYDB          | PUBLIC       |                                                           |                | 1              |
| 2018-11-26 06:08:24.263 -0800 | PUBLIC             | N          | N          | MYDB          | PUBLIC       |                                                           |                | 1              |
| 2018-12-10 09:35:32.326 -0800 | TSCHEMA            | N          | Y          | MYDB          | PUBLIC       |                                                           | TRANSIENT      | 1              |
+-------------------------------+--------------------+------------+------------+---------------+--------------+-----------------------------------------------------------+----------------+----------------+

Copy

CREATE OR ALTER SCHEMA 示例¶

创建简单架构¶

创建名为 s1 的架构：

CREATE OR ALTER SCHEMA s1;

Copy

创建或更改 s1 架构并设置属性和参数：

CREATE OR ALTER SCHEMA s1
  WITH MANAGED ACCESS
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

Copy

取消先前在架构上设置的参数¶

在修改后的架构定义中，如果缺少以前设置的参数，则会取消设置此参数。在以下示例中，为在前一个示例中创建的 s1 架构关闭托管访问：

CREATE OR ALTER SCHEMA s1
  DATA_RETENTION_TIME_IN_DAYS = 5
  DEFAULT_DDL_COLLATION = 'de';

Copy