ALTER DATABASE（目录链接）

修改现有 目录链接数据库 的属性。

数据库修改包括以下操作：

  • 启用或关闭自动发现。

  • 更改允许和阻止的命名空间。

  • 更改 Snowflake 在远程目录中自动发现架构和表时应使用的时间间隔。

  • 更改远程目录的只读或可写状态。

语法

ALTER DATABASE [ IF EXISTS ] <name> RENAME TO <new_name>

ALTER DATABASE [ IF EXISTS ] <name> SUSPEND DISCOVERY

ALTER DATABASE [ IF EXISTS ] <name> RESUME DISCOVERY

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  ADD ( '<namespace>' [ , ... ] ) TO ALLOWED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  REMOVE ( '<namespace>' [ , ... ] ) FROM ALLOWED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  UNSET ALLOWED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  ADD ( '<namespace>' [ , ... ] ) TO BLOCKED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  REMOVE ( '<namespace>' [ , ... ] ) FROM BLOCKED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  UNSET BLOCKED_NAMESPACES

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  SET SYNC_INTERVAL_SECONDS = <value>

ALTER DATABASE [ IF EXISTS ] <name> UPDATE LINKED_CATALOG
  SET ALLOWED_WRITE_OPERATIONS = { NONE | ALL }

ALTER DATABASE [ IF EXISTS ] <name> SET [ BASE_LOCATION_PREFIX = '<string>' ]
                                        [ COMMENT = '<string_literal>' ]
                                        [ CONTACT <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ]
                                        [ ICEBERG_VERSION_DEFAULT = <integer> ]
                                        [ ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE } ]

ALTER DATABASE [ IF EXISTS ] <name> UNSET { BASE_LOCATION_PREFIX         |
                                            COMMENT                      |
                                            CONTACT                      |
                                            ICEBERG_VERSION_DEFAULT      |
                                            ENABLE_ICEBERG_MERGE_ON_READ
                                          }

参数

name

指定要更改的目录链接数据库的标识符。

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

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

RENAME TO new_name

将目录链接数据库的名称更改为 new_name。新的标识符必须在账户中是唯一的。

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

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

SUSPEND DISCOVERY

暂停自动发现。如果底层问题导致 Snowflake 无法发现远程目录中的表，您可能希望暂停自动发现，以避免消耗不必要的 Credit 或资源。例如，若存在权限缺失或配置错误等底层问题，您可能需要暂停自动发现。解决问题后，可运行 ALTER DATABASE ... RESUME DISCOVERY 以恢复发现。

要确认自动发现已暂停，请调用 SYSTEM$CATALOG_LINK_STATUS 函数并验证 executionState 字段是否设置为 SUSPENDED。如果您暂停自动发现，但当前有自动发现任务正在运行，则执行状态将在任务完成后才会更改为已暂停。

备注

暂停自动发现并不会关闭自动刷新。要关闭现有 Iceberg 表的自动刷新，请参阅 启用或关闭自动刷新。

RESUME DISCOVERY

恢复自动发现。您可能需要出于以下原因恢复发现：

  • 您之前为解决问题暂停了自动发现，现在已准备好重新开始使用。

  • 您需要立即执行一次强制发现任务，以确保系统能获取最近的变更（例如已修复的权限设置）。

要确认自动发现已恢复，请调用 SYSTEM$CATALOG_LINK_STATUS 函数，然后验证 executionState 字段是否设置为 RUNNING。

UPDATE LINKED_CATALOG

更新适用于目录链接数据库的属性。您可以设置以下属性：

ADD ( 'namespace1' [ , 'namespace2' ,  ... ] ) TO ALLOWED_NAMESPACES

在远程目录中指定一个或多个命名空间，以限制自动发现的范围。Snowflake 会同步指定的命名空间及其下所有嵌套的命名空间和表。

  • 如果您创建了带有空 ALLOWED_NAMESPACES 列表的目录链接数据库，Snowflake 会同步远程目录中的 所有 命名空间和表。

    如果您后续通过指定 ALLOWED_NAMESPACES 参数来修改数据库，仅允许特定的命名空间列表，则 Snowflake 将更新目录链接的数据库，仅保留您允许的那些命名空间。所有其他命名空间和表都将从目录链接数据库中删除。

  • 如果您在创建目录链接数据库时指定了 ALLOWED_NAMESPACES 命名空间列表，则 Snowflake 仅会在该数据库中创建这些被允许的命名空间。

    如果您后续修改数据库，向 ALLOWED_NAMESPACES 列表中添加命名空间，Snowflake 将仅创建新增的命名空间，并保留现有的已允许命名空间。如果您从 ALLOWED_NAMESPACES 列表中移除命名空间，Snowflake 将仅从目录链接的数据库中删除新移除的命名空间，并保留所有其余已允许的命名空间。

如果某个嵌套命名空间位于 ALLOWED_NAMESPACES 列表中，但您将 NAMESPACE_MODE 参数设置为 IGNORE_NESTED_NAMESPACE，则 Snowflake 不会同步该嵌套命名空间及其下的任何模式和表。

REMOVE ( 'namespace1' [ , 'namespace2' ,  ... ] ) FROM ALLOWED_NAMESPACES

指定要从允许的命名空间列表中移除的远程目录中的一个或多个命名空间。

UNSET ALLOWED_NAMESPACES

将您允许的命名空间列表重置为默认值，即允许所有命名空间。

ADD ( 'namespace1' [ , 'namespace2' ,  ... ] ) TO BLOCKED_NAMESPACES

在远程目录中指定一个或多个命名空间，以进行自动发现。

Snowflake 会阻止指定的命名空间及其下所有嵌套的命名空间和表。

如果同时指定 ALLOWED_NAMESPACES 和 BLOCKED_NAMESPACES，则 BLOCKED_NAMESPACES 列表优先。例如，如果允许 ns1.ns2 但 ns1 被屏蔽，则 Snowflake 将无法同步 ns1.ns2。

REMOVE ( 'namespace1' [ , 'namespace2' ,  ... ] ) FROM BLOCKED_NAMESPACES

指定要从阻止的命名空间列表中移除的远程目录中的一个或多个命名空间。

UNSET BLOCKED_NAMESPACES

将您阻止的命名空间列表重置为默认值，即零个命名空间被阻止。

SET SYNC_INTERVAL_SECONDS = value

指定 Snowflake 在远程目录中自动发现架构和表时应使用的时间间隔（以秒为单位）。您可以通过设置更长的时间间隔来减少 Credit 消耗。

值：30 到 86400（1 天），含这两个值

默认值：30 秒

SET ALLOWED_WRITE_OPERATIONS = { NONE | ALL }

指定您的目录链接数据库是只读还是可写。

  • NONE：选择使用 时默认使用的角色和仓库。您的目录链接数据库为只读。

    当您的目录链接数据库为只读时，您运行的任何需要提交到目录的操作都会失败。例如，DROP ICEBERG TABLE。

  • ALL：选择使用 时默认使用的角色和仓库。您的目录链接数据库为可写。

    警告

    当您的目录链接数据库启用写入权限时，Snowflake 会将删除表的操作同步到远程目录，从而从两个系统中移除该表及其数据。

默认：ALL

SET ...

指定要为目录链接数据库设置的一个或多个属性或参数，以空格、逗号或换行符分隔：

BASE_LOCATION_PREFIX = 'string'

指定 Snowflake 在外部管理的 Apache Iceberg™ 表的写入路径中使用的前缀。有关详细信息，请参阅 Iceberg 表的数据和元数据目录 和 BASE_LOCATION_PREFIX。

默认：无值

COMMENT = 'string_literal'

为目录链接数据库添加注释或覆盖现有注释。

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

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

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

ICEBERG_VERSION_DEFAULT = integer

Snowflake logo in black (no text) Preview feature --- Open

Available to all accounts.

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 }

Snowflake logo in black (no text) Preview feature --- Open

Available to all accounts.

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 使用行级删除.

UNSET ...

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

  • BASE_LOCATION_PREFIX

  • COMMENT

  • CONTACT

  • ICEBERG_VERSION_DEFAULT

  • ENABLE_ICEBERG_MERGE_ON_READ

访问控制要求

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

权限

对象

备注

OWNERSHIP

正在被修改的目录链接数据库。

需要暂停或恢复自动表发现。

OWNERSHIP 或 MODIFY

正在被修改的目录链接数据库。

所有其他操作均需提供此参数。

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

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

示例

将名为 my_linked_db 的目录链接数据库的允许命名空间列表重置为默认值。

ALTER DATABASE IF EXISTS my_linked_db UPDATE LINKED_CATALOG
  UNSET ALLOWED_NAMESPACES;

将 my_namespace 添加到名为 my_linked_db 的目录链接数据库的允许命名空间列表中。

ALTER DATABASE IF EXISTS my_linked_db UPDATE LINKED_CATALOG
 ADD ('my_namespace') TO ALLOWED_NAMESPACES;