为 Snowflake Postgres 配置目录集成¶

Snowflake Postgres 目录集成允许 Snowflake 访问由 Snowflake Postgres 实例所管理的 Apache Iceberg™ 表。当您为 Snowflake Postgres 创建目录集成时，Snowflake 会自动发现 Postgres 数据库中的表，并将其作为只读的 Iceberg 表提供。

Snowflake Postgres 目录集成使用分发的凭据来访问您在云存储中的表数据和元数据。您无需配置外部卷，也无需单独管理存储凭据。

备注

Snowflake Postgres 目录集成目前仅在 AWS 上受支持。

先决条件¶

一个已启用 Snowflake Postgres 功能的 Snowflake 账户。
一个处于 READY 状态的 Postgres 实例。要创建 Postgres 实例，请参阅 CREATE POSTGRES INSTANCE。
创建目录集成的角色必须具有以下权限：
- 对 Postgres 实例具有 USAGE 权限。
- 对账户具有 CREATE INTEGRATION 权限。

注意事项¶

使用 Snowflake Postgres 目录集成时，请考虑以下几点：

Snowflake Postgres 目录集成始终使用分发的凭据。您必须设置 ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS。不支持 EXTERNAL_VOLUME_CREDENTIALS 模式。
您无需指定 REST_AUTHENTICATION。Snowflake 会自动处理与 Postgres 实例的身份验证。
自动刷新使用元数据轮询。不支持变更通知。
表是只读的。不支持对 Postgres 管理的 Iceberg 表进行写操作。
此功能不支持可突发 Postgres 实例。
此功能仅在 AWS 上受支持。

为 Snowflake Postgres 创建目录集成¶

要为 Snowflake Postgres 创建目录集成，请使用 CREATE CATALOG INTEGRATION (Snowflake Postgres) 命令。

例如：

CREATE CATALOG INTEGRATION my_postgres_catalog_int
  CATALOG_SOURCE = SNOWFLAKE_POSTGRES
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'public'
  REST_CONFIG = (
    POSTGRES_INSTANCE = 'my_pg_instance'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
    CATALOG_NAME = 'my_database'
  )
  ENABLED = TRUE;

有关完整的语法和参数参考，请参阅 CREATE CATALOG INTEGRATION (Snowflake Postgres)。

创建 Iceberg 表¶

创建目录集成后，您可以创建引用 Postgres 实例中表的 Iceberg 表。当您使用 Snowflake Postgres 目录集成创建 Iceberg 表时，您需要指定目录集成名称以及该表在 Postgres 数据库中的名称。

例如：

CREATE ICEBERG TABLE my_iceberg_table
  CATALOG = 'my_postgres_catalog_int'
  CATALOG_TABLE_NAME = 'orders'
  AUTO_REFRESH = TRUE;

其中：

CATALOG = '<catalog_integration_name>'：选择使用时默认使用的角色和仓库。指定目录集成的名称。必填。
CATALOG_TABLE_NAME = '<table_name>'：选择使用时默认使用的角色和仓库。指定该表在 Postgres 数据库中的名称。必填。
CATALOG_NAMESPACE = '<schema_name>'：选择使用时默认使用的角色和仓库。（可选）指定包含该表的 Postgres 模式。默认为在目录集成上设置的 CATALOG_NAMESPACE 值。
CATALOG_NAME = '<database_name>'：选择使用时默认使用的角色和仓库。（可选）指定包含该表的 Postgres 数据库。默认为在目录集成上设置的 CATALOG_NAME 值。
AUTO_REFRESH = TRUE：选择使用时默认使用的角色和仓库。（可选）启用自动元数据刷新。启用后，Snowflake 会定期轮询目录以获取元数据变更，并自动刷新表。

备注

当您使用 Snowflake Postgres 目录集成创建 Iceberg 表时，无需指定 EXTERNAL_VOLUME。

创建目录链接数据库¶

您无需创建单个 Iceberg 表，而是可以创建一个目录链接的数据库，该数据库会自动发现您的 Postgres 数据库中的表并与之同步。目录链接的数据库会在 Snowflake 中创建相应的模式和 Iceberg 表，这些表和您的 Postgres 数据库保持同步。

例如：

CREATE DATABASE my_postgres_db
  LINKED_CATALOG = (
    CATALOG = my_postgres_catalog_int
    ALLOWED_WRITE_OPERATIONS = NONE
  );

其中：

CATALOG = <catalog_integration_name>：选择使用时默认使用的角色和仓库。指定 Snowflake Postgres 目录集成的名称。必填。目录链接的数据库会同步由目录集成上的 CATALOG_NAME 值所指定的 Postgres 数据库。
ALLOWED_WRITE_OPERATIONS = NONE：选择使用时默认使用的角色和仓库。对于 Snowflake Postgres 目录链接的数据库而言是必需的。Snowflake Postgres 表是只读的。

创建目录链接的数据库后，Snowflake 会自动发现 Postgres 数据库中的命名空间和表，并创建相应的模式和 Iceberg 表。有关更多信息，请参阅为 Apache Iceberg™ 表使用目录链接的数据库。

查询 Iceberg 表¶

创建 Iceberg 表或目录链接的数据库后，您可以使用标准 SQL 查询这些表：

SELECT * FROM my_iceberg_table;

访问控制¶

目录集成所有者角色必须对 Postgres 实例具有 USAGE 权限。当您创建目录集成时，Snowflake 会检查此权限。

任何被授予了目录集成 USAGE 权限的角色都可以创建引用 Postgres 实例中表的 Iceberg 表。无需对 Postgres 实例授予额外权限。该角色还需要拥有在目标数据库和模式中创建表的标准 Snowflake 权限。

例如，要授予另一个角色使用该目录集成创建 Iceberg 表的能力：

GRANT USAGE ON INTEGRATION my_postgres_catalog_int TO ROLE analyst_role;
GRANT USAGE ON DATABASE my_db TO ROLE analyst_role;
GRANT USAGE ON SCHEMA my_db.public TO ROLE analyst_role;
GRANT CREATE ICEBERG TABLE ON SCHEMA my_db.public TO ROLE analyst_role;