Integrating with Iceberg catalogs

Integrating with Iceberg catalogs#

ClickHouseを外部のIcebergカタログに接続して、データを移動せずにデータレイクで高速分析クエリを実行します。 Icebergカタログは、どのテーブルが存在するか、データがオブジェクトストレージのどこにあるか、および誰がアクセスしているかを追跡するガバナンスとメタデータレイヤーです。

Sparkジョブ、Databricks、dbtなどのさまざまなパイプラインとツールは、オブジェクトストレージにデータを書き込むことができ、カタログはそのすべての単一の一貫したビューを提供します。 ClickHouse、Spark、Trinoなど、Icebergプロトコルを実装するクエリエンジンは、同じカタログに接続し、同じデータを個別に照会できます。

注釈

ClickHouseのIcebergカタログ統合は読み取り専用です。 INSERT 、UPDATE 、および`DELETE` 操作はサポートされていません。詳細は、 Known issues を参照してください。

カタログへの接続#

DataLakeCatalog データベースエンジンを使用して、ClickHouseを外部のIcebergカタログに接続します。エンジンは実験的なものであり、使用前にオプトインが必要です。

  1. カタログタイプの実験設定を有効にします。必要な設定はカタログによって異なります。完全なリストについては、 DataLakeCatalog reference を参照してください。 RESTカタログの場合

SET allow_experimental_database_iceberg = 1;

  1. 外部カタログにマッピングするデータベースを作成します。例

CREATE DATABASE my_catalog
ENGINE = DataLakeCatalog(https://catalog.example.com/api/iceberg/prj_abc123)
SETTINGS
    catalog_type = rest,
    warehouse = my-warehouse,
    auth_header = Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.example;

そこで

  • catalog_type はカタログタイプです。有効な値については、 DataLakeCatalog reference を参照してください。 - warehouse は、カタログ内のウェアハウスまたはプロジェクトの識別子です。 - auth_header は、ベアラートークン認証のHTTPヘッダーです。

ほとんどのRESTカタログでは、上記のように、auth_header を介して静的ベアラートークンを使用して認証します。 OAuth2クライアント資格情報をサポートするカタログの場合、代わりにcatalog_credential を使用します。

CREATE DATABASE my_catalog
ENGINE = DataLakeCatalog(https://catalog.example.com/api/iceberg/prj_abc123)
SETTINGS
    catalog_type = rest,
    warehouse = my-warehouse,
    catalog_credential = my-client-id:my-client-secret,
    oauth_server_uri = https://auth.example.com/oauth/token,
    auth_scope = catalog:read;

そこで

  • catalog_credential は、 client_id:client_secret 形式のOAuth2クライアント資格情報です。 - oauth_server_uri は、OAuth2承認サーバーURIです。 - auth_scope は、OAuth2スコープです。指定しない場合、デフォルトのPRINCIPAL_ROLE:ALL 。

データの照会#

データベースが作成されたら、使用可能なすべてのテーブルをリストします。

SHOW TABLES FROM my_catalog;
__OUTPUT__
┌─name──────────────────────────────┐
│ public.calls                      │
│ public.notes                      │
│ analytics.events                  │
│ duckdb_tpcds_sf_1.catalog_sales   │
└───────────────────────────────────┘

テーブルはnamespace.table_name 形式でリストされます。バッククォームを使用してそれらを参照します。

SELECT * FROM my_catalog.`public.calls` LIMIT 5;
__OUTPUT__
┌─id─┬─────────────────────────ts─┬─data───┬─category─┐
│  1 │ 2025-05-01 00:01:00.000000 │ data 1 │ bread    │
│  2 │ 2025-05-01 00:02:00.000000 │ data 2 │ fruit    │
│  3 │ 2025-05-01 00:03:00.000000 │ data 3 │ juice    │
└────┴────────────────────────────┴────────┴──────────┘

集計、フィルタ、結合、ウィンドウファンクションを含む標準SQLが適用されます。

SELECT category, count() AS total
FROM my_catalog.`public.calls`
GROUP BY category
ORDER BY total DESC;

ClickHouseは、パーティションプルーニングと述語プッシュダウンにIcebergメタデータを使用して、クエリに必要なParquetデータファイルのみを読み取ります。

目次