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

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

备注

或者，要使用第三方引擎查询 Snowflake 管理的 Iceberg 表，您可以通过 Snowflake Horizon 目录使用外部查询引擎。通过 Horizon 使用外部查询引擎，您无需将表与 Open Catalog 同步。有关更多信息，请参阅 通过 Snowflake Horizon 目录使用外部引擎查询 Apache Iceberg™ 表。

This topic covers how to sync a Snowflake-managed Iceberg table with Snowflake Open Catalog by using a catalog integration in Snowflake and an external catalog in 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 管理的表的数据和元数据目录。

以下语句为名为 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 切换已启用。

    • The Default base location combines the STORAGE_BASE_URL for the external volume you created in 第 2 步：创建外部卷 and the BASE_LOCATION_PREFIX that you set for the schema; for example s3://<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 管理的表。

语言: 中文