ALTER SCHEMA¶

修改现有架构的属性，包括重命名该架构或将其与其他架构交换，以及更改 Time Travel 数据保留期（如果您使用的是 Snowflake Enterprise Edition 或更高版本）。

另请参阅：: CREATE SCHEMA、DESCRIBE SCHEMA、DROP SCHEMA、SHOW SCHEMAS、UNDROP SCHEMA

语法¶

ALTER SCHEMA [ IF EXISTS ] <name> RENAME TO <new_schema_name>

ALTER SCHEMA [ IF EXISTS ] <name> SWAP WITH <target_schema_name>

ALTER SCHEMA [ IF EXISTS ] <name> SET {
                                      [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
                                      [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
                                      [ EXTERNAL_VOLUME = <external_volume_name> ]
                                      [ CATALOG = <catalog_integration_name> ]
                                      [ ICEBERG_VERSION_DEFAULT = <integer> ]
                                      [ ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE } ]
                                      [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
                                      [ DEFAULT_DDL_COLLATION = '<collation_specification>' ]
                                      [ DEFAULT_NOTEBOOK_COMPUTE_POOL_CPU = '<compute_pool_name>' ]
                                      [ DEFAULT_NOTEBOOK_COMPUTE_POOL_GPU = '<compute_pool_name>' ]
                                      [ LOG_LEVEL = '<log_level>' ]
                                      [ TRACE_LEVEL = '<trace_level>' ]
                                      [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
                                      [ CLASSIFICATION_PROFILE = '<profile_name>' ]
                                      [ COMMENT = '<string_literal>' ]
                                      [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>' ]
                                      [ REPLICABLE_WITH_FAILOVER_GROUPS = { 'YES' | 'NO' } ]
                                      [ BASE_LOCATION_PREFIX = '<string>']
                                      [ DEFAULT_STREAMLIT_NOTEBOOK_WAREHOUSE = '<warehouse_name>']
                                      [ CONTACT <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ]
                                      [ OBJECT_VISIBILITY = PRIVILEGED } ]
                                      [ ENABLE_DATA_COMPACTION = { TRUE | FALSE } ]
                                      }

ALTER SCHEMA [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER SCHEMA [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]

ALTER SCHEMA [ IF EXISTS ] <name> UNSET {
                                        DATA_RETENTION_TIME_IN_DAYS         |
                                        MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                        EXTERNAL_VOLUME                     |
                                        CATALOG                             |
                                        ICEBERG_VERSION_DEFAULT             |
                                        ENABLE_ICEBERG_MERGE_ON_READ        |
                                        REPLACE_INVALID_CHARACTERS          |
                                        DEFAULT_DDL_COLLATION               |
                                        LOG_LEVEL                           |
                                        TRACE_LEVEL                         |
                                        STORAGE_SERIALIZATION_POLICY        |
                                        COMMENT                             |
                                        CATALOG_SYNC                        |
                                        REPLICABLE_WITH_FAILOVER_GROUPS     |
                                        BASE_LOCATION_PREFIX                |
                                        DEFAULT_STREAMLIT_NOTEBOOK_WAREHOUSE|
                                        CONTACT <purpose>
                                        CLASSIFICATION_PROFILE
                                        OBJECT_VISIBILITY                   |
                                        CONTACT <purpose>                   |
                                        CLASSIFICATION_PROFILE              |
                                        ENABLE_DATA_COMPACTION
                                        }
                                        [ , ... ]

ALTER SCHEMA [ IF EXISTS ] <name> { ENABLE | DISABLE } MANAGED ACCESS

Copy

参数¶

name

指定要更改的架构的标识符。如果标识符包含空格、特殊字符或大小写混合字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

RENAME TO new_schema_name

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

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

您可以将对象移至其他数据库，同时选择性重命名架构。为此，请在 db_name.new_schema_name 表单中，指定一个包含新数据库名称的限定 new_schema_name 值。

备注

目标数据库必须已经存在。此外，新位置中不能存在同名架构；否则，该语句将返回错误。

重命名对象时，引用该对象的其他对象必须使用新名称进行更新。

SWAP WITH target_schema_name

在两个指定的架构之间交换所有对象（表、视图等）和元数据，包括标识符。此外，交换对他们包含的架构和对象的所有访问控制权限。SWAP WITH 本质上以单个操作重命名两个架构。

SET ...

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

DATA_RETENTION_TIME_IN_DAYS = integer

指定可以对架构执行 Time Travel 操作（CLONE 和 UNDROP）的天数，并指定在架构中创建的所有表的默认 Time Travel 保留时间。

您可以指定的值取决于您使用的 Snowflake Edition：

Standard Edition：0 或 1
Enterprise Edition（或更高版本）：0 至 90

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。

ICEBERG_VERSION_DEFAULT = integer

Specifies the version of the Apache Iceberg™ table specification that Iceberg tables conform to.

Values:

2: New tables conform with Iceberg version 2.

3: New tables conform with Iceberg version 3.

小心

Before you use other engines to upgrade an Iceberg tables format-version in table properties to v3, ensure that the table isn't used by engines or applications that don't yet support v3. Downgrading format versions isn't supported in the Apache Iceberg specification. Therefore, all readers and writers must support v3. The default version for Iceberg tables in Snowflake is v2, which can be configured to v3 if needed. Using Snowflake to perform in-place version upgrades isn't supported at this time.

Default:: 2

For more information about this parameter, see ICEBERG_VERSION_DEFAULT.

ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE }

Specifies whether to enable merge-on-read behavior for Apache Iceberg™ tables.

Values:

TRUE: New tables use merge-on-read behavior.

FALSE: New tables use copy-on-write behavior.

Default:

TRUE

For a detailed description of this parameter, see ENABLE_ICEBERG_MERGE_ON_READ. For more information about merge-on-read and copy-on-write behavior in Snowflake, see 使用行级删除.

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。

DEFAULT_NOTEBOOK_COMPUTE_POOL_CPU = compute_pool_name

CPU 计算池名称，用于覆盖 Snowflake 在账户中为运行 Notebooks 而配置的默认 CPU 计算池。有关更多信息，请参阅 System compute pools。

DEFAULT_NOTEBOOK_COMPUTE_POOL_GPU = compute_pool_name

GPU 计算池名称，用于覆盖 Snowflake 在账户中为运行 Notebooks 而配置的默认 GPU 计算池。有关更多信息，请参阅 System compute pools。

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

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

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

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

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

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

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

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

CLASSIFICATION_PROFILE = 'profile_name'

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

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。

默认：无值

REPLICABLE_WITH_FAILOVER_GROUPS = { 'YES' | 'NO' }

指定此架构是否符合复制条件。您可以将此属性设置为 NO，以防止复制数据库中的单个架构。

有关此参数的详细信息，请参阅故障转移组的架构级复制。

默认：'YES'

DEFAULT_STREAMLIT_NOTEBOOK_WAREHOUSE = 'warehouse_name'

指定使用 SQL 创建笔记本时要使用的默认仓库。

BASE_LOCATION_PREFIX = 'string'

指定 Snowflake 在 Snowflake 管理的 Apache Iceberg™ 表的写入路径中使用的前缀。有关更多信息，请参阅“Snowflake 参数”主题中的 Iceberg 表的数据和元数据目录和 BASE_LOCATION_PREFIX。

默认：无值

OBJECT_VISIBILITY = PRIVILEGED

指定仅当前账户中已被显式授予该对象权限的角色，方可查看到此对象。这是 Snowflake 中的默认行为。

有关示例，请参阅使数据库对象在 Universal Search 中可被发现。

ENABLE_DATA_COMPACTION = { TRUE | FALSE }

指定 Snowflake 是否应对 Snowflake 管理的 Apache Iceberg™ 表启用数据压缩功能。

TRUE：选择使用时默认使用的角色和仓库。Snowflake 对表执行数据压缩。
FALSE：选择使用时默认使用的角色和仓库。Snowflake 不会对表执行数据压缩。

默认：TRUE

有关更多信息，请参阅 ENABLE_DATA_COMPACTION 和。

UNSET ...

指定要为数据库取消设置的一个（或多个）属性和/或参数，这会将它们重置为默认值：

DATA_RETENTION_TIME_IN_DAYS
MAX_DATA_EXTENSION_TIME_IN_DAYS
EXTERNAL_VOLUME
CATALOG
ICEBERG_VERSION_DEFAULT
ENABLE_ICEBERG_MERGE_ON_READ
REPLACE_INVALID_CHARACTERS
DEFAULT_DDL_COLLATION
TAG tag_name [ , tag_name ... ]
LOG_LEVEL
TRACE_LEVEL
STORAGE_SERIALIZATION_POLICY
COMMENT
CATALOG_SYNC
REPLICABLE_WITH_FAILOVER_GROUPS
BASE_LOCATION_PREFIX
DEFAULT_STREAMLIT_NOTEBOOK_WAREHOUSE
CONTACT purpose
CLASSIFICATION_PROFILE
OBJECT_VISIBILITY
ENABLE_DATA_COMPACTION

您可以使用单个 ALTER 语句重置多个属性/参数；但是，每个属性/参数必须用逗号分隔。重置属性/参数时，请仅指定名称；指定属性的值将返回错误。

{ ENABLE | DISABLE } MANAGED ACCESS

为架构启用托管访问，或禁用以将托管访问架构转换为常规架构。托管访问架构将权限管理集中到架构所有者。

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

使用说明¶

要重命名架构，用于执行操作的角色必须具有架构数据库的 CREATE SCHEMA 权限和架构的 OWNERSHIP 权限。
要交换两个架构，用于执行操作的角色必须对两个架构都具有 OWNERSHIP 权限。
要将常规架构转换为托管访问架构，请执行以下操作：
- 架构所有者（即，具有架构的 OWNERSHIP 权限的角色）还必须具有全局 MANAGE GRANTS 权限。因为具有 MANAGE GRANTS 权限的另一个角色可能已经定义对架构中指定类型的对象的未来授权，所以需要此权限。在常规架构成为托管访问架构之后，架构所有者可以撤销未来授权，无需了解为什么具有 MANAGE GRANTS 权限的角色向他们授权。
- 必须使用带 FUTURE 关键字的 REVOKE <privileges> ... FROM ROLE，撤销所有开放的未来授权。
在将常规架构转换为托管访问架构之后，保留以前授予的对各个对象的所有权限；但是，对象所有者不能授予对这些对象的更多权限。
要将托管访问架构转换为常规架构，仅当当前架构已定义未来权限授予时，架构所有者才必须具有全局 MANAGE GRANTS 权限。
For schemas in a catalog-linked database, this command only supports the following parameters:
- SET/UNSET with the following options:
  - CLASSIFICATION_PROFILE
  - COMMENT
  - CONTACT
  - STORAGE_SERIALIZATION_POLICY
  - TAG
- ENABLE MANAGED ACCESS and DISABLE MANAGED ACCESS.
To specify the default version of the Apache Iceberg™ specification that Iceberg tables conform to, the role used to perform the operation must have the OWNERSHIP privilege on the schema.
关于元数据：

注意

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

示例¶

将架构 schema1 重命名为 schema2：

ALTER SCHEMA IF EXISTS schema1 RENAME TO schema2;

Copy

将常规架构转换为托管访问架构：

ALTER SCHEMA schema2 ENABLE MANAGED ACCESS;

Copy