Integrating with Iceberg catalogs

Integrating with Iceberg catalogs#

カタログサービスは、データレイクの集中化された「頭脳」として機能し、論理テーブル定義から物理ストレージを分離します。メタデータ、スキーマ、およびパーティショニングの単一の信頼できるソースを維持することにより、Postgres、Spark、Trinoなどの複数の独立したエンジンが、破損やスキーマドリフトのリスクなしで同じデータを共有できます。

Postgres Analytics AcceleratorPGAAは、サードパーティのカタログと統合して、Postgres展開内の分析ワークロードにシームレスなデータレイク接続を提供します。

PGAAは、次のカタログ実装を使用してIcebergテーブルの読み取りおよび書き込み Icebergカタログを使用する をサポートしています。

  • RESTカタログ Lakekeeper、Tabular、Apache Polaris、Project Nessieなど、Apache Iceberg REST APIに続くサービス。

  • AWS S3テーブル クラウドスケールの分析用に設計された高性能のAWSネイティブカタログ。

PGAAを使用した外部Icebergカタログの管理には、2つの主なフェーズが含まれます。

  1. カタログ接続の追加 。

  2. カタログテーブルの登録 。

注釈

外部カタログを使用する場合、保存場所を作成する必要はありません。テーブルは、保存場所またはカタログにリンクされています。

カタログ接続の追加#

ファンクション pgaa.add_catalog() を使用して、外部IcebergカタログをPostgresインスタンスに登録します。このファンクションは、カタログの場所とログイン方法をPostgresに伝えるメタデータリンクを作成します。また、カタログ接続と資格情報を検証し、構成を保存します。

SELECT pgaa.add_catalog(
    catalog_name TEXT,
    catalog_type TEXT,
    catalog_options JSON
);

次のカタログタイプのいずれかを指定します。

  • iceberg-rest Iceberg RESTカタログLakekeeper、Snowflake Polaris、Tabularの場合。

  • iceberg-s3tables AWS S3テーブルの場合。

RESTカタログ#

ほとんどのRESTカタログサービスでは、JSONオブジェクトを介してエンドポイントとトークンの詳細を提供します。

SELECT pgaa.add_catalog(
    my_iceberg_catalog,
    iceberg-rest,
    {
        "url": "https://your-catalog-endpoint.com",
        "warehouse_name": "your_warehouse_name",
        "warehouse": "your_warehouse_id",
        "token": "your_secret_auth_token"
    }
);

Snowflakeのような一部のIceberg RESTカタログプロバイダーは、認証のより高度な設定を必要とします。 PGAAは、安全なローテーション認証を処理するための完全なOAuth2オプションをサポートしています。例

SELECT pgaa.add_catalog(
    my_iceberg_catalog,
    iceberg-rest,
    {
        "oauth2.grant_type": "client_credentials",
        "oauth2.client_id": "oauth-client-id",
        "oauth2.client_secret": "oauth-client-secret",
        "oauth2.token_uri": "https://EXAMPLE-polaristest.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens",
        "oauth2.scope": "PRINCIPAL_ROLE:read_only"
    }
);

AWS S3テーブル#

AWS S3テーブルカタログの場合、AmazonリソースネームARNとリージョンを指定します。

SELECT pgaa.add_catalog(
    my_s3_catalog,
    iceberg-s3tables,
    {
        "arn": "arn:aws:s3tables:us-east-1:123456:bucket/analytics",
        "region": "us-east-1"
    }
);

カタログ構成の検証#

カタログを追加した後、次の機能を使用して接続を確認し、利用可能なデータを探索します。

  • 登録されたカタログをリストします

SELECT * FROM pgaa.list_catalogs();

  • 構成の接続と書き込み権限をテストします。接続が成功した場合、ファンクションはNULL を結果ます。例

SELECT pgaa.test_catalog(my_iceberg_catalog, test_writes := FALSE);

  • インポートする前に、外部カタログ内で使用可能なテーブルを参照します。

SELECT pgaa.list_catalog_tables(my_iceberg_catalog);

カタログの登録とメンテナンスをサポートするファンクションの完全なリストについては、 カタログファンクション リファレンスセクションを参照してください。

カタログテーブルの登録#

カタログ接続を確立したら、Postgresが外部データを認識および照会できるように、そのメタデータを登録する必要があります。 PGAAは、登録のための3つの異なるパスを提供します。

カタログの添付#

カタログを添付すると、Postgresと外部のIcebergメタデータサービス間の動的リンクが確立されます。静的インポートとは異なり、この方法では、Postgres環境が進化するデータレイクとの同期を維持します。

カタログをアタッチすると、PGAAはカタログを継続的にポーリングして新しいテーブルまたはスキーマの進化を検出するバックグラウンドワーカーを起動します。 PGAAは、カタログ側で定義された名前空間階層を優先します。接続されたカタログに、データベース上の既存のテーブルと名前を共有するテーブルが含まれている場合、バックグラウンドワーカーはそれをスキップして上書きを回避します。

同期プロセスは、2つの主要な構成パラメーターによって管理されます。

  • pgaa.metastore_sync_poll_rate_s ポーリング頻度を制御します。

  • pgaa.metastore_sync_stale_duration_s メタデータの鮮度のしきい値を定義します。

pgaa.attach_catalog() ファンクションを使用してカタログを添付します。

SELECT pgaa.attach_catalog(my_iceberg_catalog);

Postgres環境でテーブルが作成されたことを確認します。カタログテーブルがPostgresインスタンスに登録されると、標準のテーブルと同じようにアクセスできます。

pgaa.detach_catalog() ファンクションを使用して、カタログを切断できます。

SELECT pgaa.detach_catalog(my_iceberg_catalog);

このファンクションは、バックグラウンド同期ワーカーを停止し、Icebergメタデータサービスへのダイナミックリンクを削除します。カタログは追加されたままで pgaa.list_catalogs() に表示され、後で資格情報を再入力せずに再接続できますが、更新のポーリングや新しいテーブルの自動的なマップは行われません。オプションCASCADE を使用する場合、このカタログによって管理されているすべてのテーブルもドロップされます。

カタログのインポート#

継続的にポーリングする代わりに、1回だけの手動同期を実行できます。 Postgresはテーブルの現在の状態を取得しますが、インポートを再度実行するまで将来の変更は検出しません。インポートされたカタログに、データベース上の既存のテーブルと名前を共有するテーブルが含まれている場合、PGAAはそのテーブルの作成をスキップして、上書きを回避します。カタログをインポートして、次のバックグラウンドポーリングサイクルを待たずに更新を強制することもできます。

pgaa.import_catalog() ファンクションを使用してカタログをインポートします。

SELECT pgaa.import_catalog(my_iceberg_catalog);

オプションで名前空間フィルタを指定するコマンドを使用して、この特定のIceberg名前空間内のテーブルのみがインポートされるようにできます。例

SELECT pgaa.import_catalog(my_iceberg_catalog, tpcds_sf_1000);

新しいテーブルがPostgres環境に表示されることを確認します。追加の構成なしで、データレイクに対して標準のSQLクエリを直接実行できます。

カタログ管理テーブルの作成#

カタログ管理テーブルでは、既存のカタログ接続を活用しながら、カスタムローカルテーブル名を定義し、特定のスキーマ配置を選択し、列を明示的にマップできます。

手動登録は、カタログ全体を添付するよりも柔軟性があります。 Postgres名前空間を完全に制御できるため、Icebergカタログ内の場所に関係なく、任意のローカルスキーマにテーブルを配置できます。

手動テーブルの同期は、データレイクで発生する変更の種類によって異なります。

Change type

Synchronization

Behavior details

Data changes

Automatic

Every query resolves the latest Iceberg snapshot. New, updated, or deleted rows are reflected immediately.

Partition evolution

Automatic

Iceberg stores partitioning logic in metadata. If the partitioning strategy changes, PGAA handles the file-pruning adjustments behind the scenes.

Schema evolution

Manual

Structural changes (new or deleted columns) are ignored or will cause errors. You must update the Postgres table using ALTER TABLE to match the new remote schema.

CREATE TABLE ... USING PGAA WITH 構文を使用して、カタログ管理テーブルを作成します。例

CREATE TABLE managed_sales_data (
    id BIGINT,
    sale_date TIMESTAMP,
    amount NUMERIC
)
USING PGAA
WITH (
    pgaa.format = iceberg,
    pgaa.managed_by = my_iceberg_catalog,
    pgaa.catalog_namespace = public,
    pgaa.catalog_table = managed_sales_data
);

そこで

  • pgaa.format テーブルフォーマット’iceberg’を設定します。

  • pgaa.managed_by 特定の外部カタログpgaa.add_catalog によって以前に定義された外部カタログを指定します。

  • pgaa.catalog_namespace Icebergカタログ内でテーブルが存在する名前空間を定義します。

  • pgaa.catalog_table データレイクに表示されるテーブルの名前を指定します。

注釈

列定義を空の`()` のままにすると、PGAAはIcebergカタログからスキーマを自動的に検出およびマッピングします。

目次