为 Apache Iceberg™ 表使用目录链接的数据库

通过目录链接的数据库，您可以在 Snowflake 中访问多个远程 Iceberg 表，而无需创建单独的 外部管理表。

目录链接的数据库是一种连接到外部 Iceberg REST 目录的 Snowflake 数据库。Snowflake 会自动与外部目录同步以检测命名空间和 Iceberg 表，并将远程表注册到目录链接的数据库。目录链接的数据库还支持创建和删除架构或 Iceberg 表。

注意事项

重要

在预览期间，目录链接的数据库不支持只读模式。若删除表或写入数据，这些更改也会在远程目录中执行。

使用目录链接的数据库时请注意以下事项：

  • 仅当您使用 Iceberg REST 的目录集成（例如 Snowflake Open Catalog）时才支持。

  • 计费：在预览期间，Snowflake 不对目录链接的数据库计费。计费从 2025 年 9 月 1 日开始。为了帮助您预览成本，METERING_HISTORY 和 METERING_DAILY_HISTORY 视图将在计费开始之前，显示用于目录链接的数据库的 Credit。

  • 要将自动表发现限制为一组特定的命名空间，请使用 ALLOWED_NAMESPACES 参数。您也可以使用 BLOCKED_NAMESPACES 参数来屏蔽一组命名空间。

  • Snowflake 不同步远程目录访问控制（用户或角色）。

  • 您可以在目录链接的数据库中创建架构或外部管理的 Iceberg 表。目前不支持创建其他 Snowflake 对象。

  • 延迟：

    • 对于链接到远程目录中 7,500 个命名空间的数据库，发现命名空间和表大约需要一小时。

    • 对于包含 500,000 个表的远程目录，自动刷新过程大约需要一小时才能完成。对于具有不同延迟要求的命名空间，我们建议您创建单独的目录链接的数据库。每个数据库都应引用具有相应自动刷新间隔 (REFRESH_INTERVAL_SECONDS) 的目录集成。

  • 对于目录链接的数据库中的 Iceberg 表：

    • Snowflake 不复制远程目录表属性（例如保留策略或缓冲区），并且目前不支持更改表属性。

    • 默认情况下，自动刷新 处于启用状态。如果外部表的 table-uuid 和目录链接的数据库表不匹配，则刷新失败，Snowflake 将该表从目录链接的数据库中删除；Snowflake 不会更改远程表。

    • 如果您从远程目录中删除表，Snowflake 会将该表从目录链接的数据库中删除。此操作是异步进行的，因此您可能不会立即在远程目录中看到更改。

    • 如果您重命名远程目录中的表，Snowflake 会从目录链接的数据库中删除现有表，并使用新名称创建一个表。

    • 支持掩码策略和标签。不支持其他特定于 Snowflake 的功能，包括复制、克隆和共享。

    • 您为 NAMESPACE_FLATTEN_DELIMITER 参数选择的字符不会出现在远程命名空间中。在自动发现过程中，Snowflake 会跳过任何包含分隔符的命名空间，并且不会在您目录链接的数据库中创建相应的架构。

    • 如果为 NAMESPACE_FLATTEN_DELIMITER 参数指定 _、$、大写字母或数字以外的任何值，则在查询表时必须将架构名称放在引号中。

    • 对于链接到 AWS Glue 的数据库，必须使用小写字母，并将架构、表和列名称用双引号引起来。对于其他仅支持小写标识符的 Iceberg REST 目录，这也是必需的。

      以下示例显示了有效查询：

      CREATE SCHEMA “s1”;
      Copy

      以下语句无效，因为它们使用大写字母或省略了双引号：

      CREATE SCHEMA s1;
CREATE SCHEMA "Schema1";
      Copy

    • 不支持使用 UNDROP ICEBERG TABLE。

    • 使用外部卷的表支持与列表共享。目前不支持直接共享。

  • 写入目录链接的数据库中的表：

    • 不支持已售凭据。

    • 目前不支持写入嵌套命名空间中的表。

工作流程

以下步骤介绍如何创建目录链接的数据库、检查 Snowflake 与目录之间的同步状态，以及在数据库中创建或查询表。

  1. 配置访问权限

  2. 创建目录链接数据库

  3. 检查目录同步状态

  4. 查询表 或 写入远程目录

配置访问权限

在创建目录链接的数据库之前，请从以下选项中选择一种来配置外部目录及表存储的访问权限。

选项 1：配置外部卷和目录集成

使用此选项时，您需要配置一个 外部卷 和一个 目录集成。如果您的远程 Iceberg 目录不支持凭证分发，或需要向远程目录中的 Iceberg 表执行写入操作，请选择此选项。

首先，为存储远程 Iceberg 表数据和元数据的云存储服务配置外部卷：

然后，为您的远程 Iceberg 目录配置目录集成：

选项 2：配置支持凭证分发的目录集成

备注

只有在 Amazon S3 中存储数据和元数据的表才支持此功能。此选项目前不支持外部写入。

使用此选项时，您的远程 Iceberg 目录必须支持凭证分发。

有关说明，请参阅 为 Apache Iceberg™ 表使用由目录分发的凭据。

创建目录链接数据库

使用 CREATE DATABASE（目录链接） 命令创建目录链接的数据库：

以下示例创建一个使用外部卷的目录链接的数据库。该示例指定 60 秒同步间隔（默认值为 30 秒）。同步间隔用于指示 Snowflake 轮询远程目录的频率。

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int',
    BLOCKED_NAMESPACES = ('my_blocked_namespace'),
    NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE,
    NAMESPACE_FLATTEN_DELIMITER = '-'
    SYNC_INTERVAL_SECONDS = 60
  )
  EXTERNAL_VOLUME = 'my_external_vol';
Copy

备注

此示例指定 NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE，该参数指示 Snowflake 为目录中 所有 命名空间层级的表建立链接。对于嵌套命名空间中的表，Snowflake 使用 NAMESPACE_FLATTEN_DELIMITER 参数来构建扁平化命名空间。

有关更多信息，请参阅 CREATE DATABASE（目录链接）。

或者，也可创建使用凭证分发功能的目录链接的数据库。此示例同时指定了一个允许的命名空间。

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int_vended_creds',
    ALLOWED_NAMESPACES = ('my_namespace')
  );
Copy

检查目录同步状态

要检查 Snowflake 是否已成功将远程目录链接至数据库，请使用 SYSTEM$CATALOG_LINK_STATUS 函数。

该函数还可提供相关信息，帮助您识别远程目录中同步失败的表。

SELECT SYSTEM$CATALOG_LINK_STATUS('my_linked_db');
Copy

查询表

创建目录链接的数据库后，Snowflake 会启动表发现过程，并自动使用 SYNC_INTERVAL_SECONDS 参数值（默认间隔为 30 秒）轮询已链接的目录以检查变更。

在数据库中，远程目录的允许命名空间将显示为架构，而 Iceberg 表将出现在其各自的架构之下。

您可以使用 SELECT 语句查询远程表。

备注

Snowflake 会自动将未加引号的标识符（表名和列名）转换为大写。如果您的外部 Iceberg 目录使用区分大小写的标识符，则必须用双引号将表名和列名引起来。

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

例如：

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;
Copy

写入远程目录

您可以使用 Snowflake 在已链接目录中创建命名空间和 Iceberg 表。有关详细信息，请参阅以下主题：

语言: 中文