将 Snowflake 管理的表与 Snowflake Open Catalog 同步

要使用 Apache Spark™ 等第三方引擎查询 Snowflake 托管的 Apache Iceberg™ 表，可以将表与 Snowflake Open Catalog 同步。

本主题介绍如何使用 Snowflake 中的目录集成和 Open Catalog 中的外部目录将 Snowflake 管理的 Iceberg 表与 Snowflake Open Catalog 同步。

重要

如果您的第三方引擎只能查询目录中位于第二级命名空间以下的表，则必须将 Snowflake 管理的 Iceberg 表同步至仅含单层父命名空间的 Open Catalog 中。否则，Snowflake 会将该表同步至 Open Catalog 中的第三级命名空间，导致您无法查询该表。

如要将 Snowflake 管理的 Iceberg 表配置为同步至单层（而非双层）父命名空间，请在创建数据库时将 CATALOG_SYNC_NAMESPACE_MODE 属性设置为 FLATTEN。有关信息，请参阅 CREATE DATABASE。现有数据库不支持修改此配置模式。对于已启用 CATALOG_SYNC 的现有数据库，其表将始终以双层父命名空间结构同步至 Open Catalog。

第 1 步：设置 BASE_LOCATION_PREFIX

Snowflake 会将每个 Iceberg 表的文件写入包含动态生成的字符串（随机 ID）的目录下。

为确保 Open Catalog 能够识别您同步的所有 Snowflake 管理的表，我们建议在账户、数据库或架构级别使用 label-base_location_prefix`（例如 ``my-open-catalog-tables`），并在 CREATE ICEBERG TABLE 语句中省略 BASE_LOCATION 参数。这样，所有在该账户、数据库或架构下创建的 Iceberg 表文件都将组织在一个已知目录中，该目录名称与您设置的前缀相同。有关更多信息，请参阅 Snowflake 管理的表的数据和元数据目录 <label-tables_iceberg_configure_external_volume_base_location>。

以下语句为名为 open_catalog 的架构设置 BASE_LOCATION_PREFIX：

ALTER SCHEMA open_catalog
  SET BASE_LOCATION_PREFIX = 'my-open-catalog-tables';
Copy

第 2 步：创建外部卷

如果您还没有，请先在 Snowflake 中创建一个外部卷，该卷提供对要存储表数据和元数据的云存储位置的访问权限。

备注

在指定 STORAGE_BASE_URL 的路径时，请勿包含 BASE_LOCATION_PREFIX。

完成云存储服务的说明：

第 3 步：配置 Open Catalog 资源

接下来，完成本节中的步骤，在 Open Catalog 账户中创建外部目录和服务连接。

  1. 按照 创建目录 中的说明，在 Open Catalog 账户中创建外部目录。确保为外部目录配置了以下设置：

    • External 切换已启用。

    • Default base location 由您在 第 2 步：创建外部卷 中创建的外部存储卷的 STORAGE_BASE_URL 与您为架构设置的 BASE_LOCATION_PREFIX 组合而成；例如 https://<storage_base_url>/<base_url_prefix>/。

    Open Catalog 将 Snowflake 管理的表同步到此外部目录。

  2. 如果您还没有 Snowflake 的服务连接，请按照 配置服务连接 中的说明在您的 Open Catalog 账户中为 Snowflake 引擎创建连接。

  3. 为外部目录配置目录角色，该角色具有允许访问外部目录的权限。有关说明，请参阅 向目录授予权限。

    目录角色必须对目录具有以下特权：

    • TABLE_CREATE

    • TABLE_WRITE_PROPERTIES

    • TABLE_DROP

    • NAMESPACE_CREATE

    • NAMESPACE_DROP

    您可以将这些特权中的每一个授予目录角色，也可以授予 CATALOG_MANAGE_CONTENT 特权，其中包括这些权限。有关更多信息，请参阅 Snowflake Open Catalog 的目录特权。

  4. 将目录角色附加到服务连接的主体角色。这允许服务连接访问目录。有关说明，请参阅 向主体角色授予目录角色。

第 4 步：为 Open Catalog 创建目录集成

通过 CREATE CATALOG INTEGRATION (Snowflake Open Catalog) 命令为 Open Catalog 创建目录集成。

对于 CATALOG_NAME，指定您在 Open Catalog 账户中配置的外部目录的名称。Snowflake 会将表及其在 Snowflake 中的父命名空间同步至 Open Catalog 中的此外部目录。例如，如果您在 Snowflake 中注册了一个 db1.public.table1 Iceberg 表，并且在目录集成中指定了 catalog1，则该表将与 Open Catalog 同步，并使用以下完全限定名称：catalog1.db1.public.table1。

要解决创建目录集成时出现的问题，请参阅 您无法为 Open Catalog 创建目录集成。

CREATE OR REPLACE CATALOG INTEGRATION my_open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.cn/polaris/api/catalog'
    CATALOG_NAME = 'myOpenCatalogExternalCatalogName'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'myClientId'
    OAUTH_CLIENT_SECRET = 'myClientSecret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;
Copy

备注

您可以使用此目录集成来同步一个或多个 Snowflake 管理的表。

第 5 步：设置目录同步

为使 Snowflake 能将 Snowflake 管理的 Iceberg 表同步至 Open Catalog，您必须指定 Open Catalog 中 Snowflake 应将表同步至的外部目录。为进行这项配置，您需要将 CATALOG_SYNC 参数设置为 Open Catalog 的某个目录集成的名称。

在数据库级别设置 CATALOG_SYNC

此示例展示了如何在数据库级别设置 CATALOG_SYNC 参数。执行以下语句后，Snowflake 会将 db1 数据库中的所有 Snowflake 管理的 Iceberg 表同步至您为 my_open_catalog_int 录集成指定的 Open Catalog 外部目录。有关更多信息，请参阅 ALTER DATABASE 命令。

ALTER DATABASE db1 SET CATALOG_SYNC = 'my_open_catalog_int';
Copy

您也可以在创建数据库时设置 CATALOG_SYNC。例如：

CREATE DATABASE db2
  CATALOG_SYNC = 'my_open_catalog_int';
Copy

有关更多信息，请参阅 CREATE DATABASE。

在架构级别设置 CATALOG_SYNC

此示例展示了如何在架构级别设置 CATALOG_SYNC 参数。执行以下语句后，Snowflake 会将 public 架构中的所有 Snowflake 管理的 Iceberg 表同步至您为 my_open_catalog_int 目录集成指定的 Open Catalog 外部目录。有关更多信息，请参阅 ALTER SCHEMA 命令。

ALTER SCHEMA public SET CATALOG_SYNC = 'my_open_catalog_int';
Copy

您也可以在创建架构时设置 CATALOG_SYNC。例如：

CREATE SCHEMA schema1
  CATALOG_SYNC = 'my_open_catalog_int';
Copy

有关更多信息，请参阅 CREATE SCHEMA。

备注

  • 您还可以执行以下操作：

    • 在账户或表级别设置 CATALOG_SYNC。

    • 在不同级别替换 CATALOG_SYNC。例如，您可以在数据库级别设置 CATALOG_SYNC，然后为数据库中的 myschema 架构替换该值。这样，myschema 架构中的 Snowflake 管理的 Iceberg 表将同步至 Open Catalog 中与其他数据库内 Snowflake 管理的 Iceberg 表不同的外部目录。

    有关更多信息，请参阅 CATALOG_SYNC 和 参数层次结构和类型。

  • 要查看 Snowflake 管理的 Iceberg 表同步至的 Open Catalog 目录集成名称，请运行 SHOW ICEBERG TABLES 命令并查看输出中的 catalog_sync_name 列。

第 6 步：创建 Snowflake 管理的表

使用 CREATE ICEBERG TABLE（使用 Snowflake 作为 Iceberg 目录） 命令创建 Snowflake 管理的 Iceberg 表。

重要

要确保在 Open Catalog 中对表正确实施特权，请确保在创建表之前满足特定条件。这些条件与目录的目录结构层次结构有关。有关这些条件以及如何满足这些条件的说明，请参阅 Snowflake Open Catalog 文档中 组织目录内容 中的说明。

USE SCHEMA open_catalog;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (col1 INT)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume';
Copy

对于前述示例语句中使用的 BASE_LOCATION_PREFIX (my-open-catalog-tables) 和表名 (my_iceberg_table)，Snowflake 会将表文件写入以下路径：

  • STORAGE_BASE_URL/my-open-catalog-tables/my_iceberg_table.randomId/data/

  • STORAGE_BASE_URL/my-open-catalog-tables/my_iceberg_table.randomId/metadata/

当您在 Snowflake 中修改表时，更改会自动与 Open Catalog 账户中的外部目录同步。其他引擎（如 Apache Spark™）可以通过连接到 Open Catalog 查询表。

要排查创建 Snowflake 管理的表的问题，请参阅 您无法创建 Snowflake 管理的表。

语言: 中文