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

Considerations for using a catalog-linked database for Iceberg tables¶

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

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

• Billing: During the preview period, Snowflake doesn't bill for catalog-linked databases. Billing starts when Apache Iceberg™ catalog-linked databases become generally available.

• 要将自动表发现限制为一组特定的命名空间，请使用 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。

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

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

  • 不支持已售凭据。

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

  • Position row-level deletes (https://iceberg.apache.org/spec/#row-level-deletes) are supported for tables stored on Amazon S3, Azure, or Google Cloud. Row-level deletes with equality delete files aren’t supported. For more information about row-level deletes, see 使用行级删除. To turn off position deletes, which enable running the Data Manipulation Language (DML) operations in copy-on-write mode, set the ENABLE_ICEBERG_MERGE_ON_READ parameter to FALSE at the table, schema, or database level.

Workflow to configure access to your external catalog and table storage¶

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

1. Configure access to your external catalog and table storage

2. 创建目录链接数据库

3. 检查目录同步状态

4. Query a table in your catalog-linked database 或 写入远程目录

Configure access to your external catalog and table storage¶

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

创建目录链接数据库¶

使用 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';

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

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

检查目录同步状态¶

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

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

SELECT SYSTEM$CATALOG_LINK_STATUS('my_linked_db');

Query a table in your catalog-linked database¶

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

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

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

例如：

USE DATABASE my_linked_db;

SELECT * FROM my_namespace.my_iceberg_table
  LIMIT 20;

写入远程目录¶

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

• 对外部托管的 Apache Iceberg™ 表的写入支持

• 使用 CREATE SCHEMA 在外部目录中创建命名空间

• 在目录链接的数据库中创建 Iceberg 表