Skip to main content
SeaweedFS カタログとのインテグレーションは、Iceberg テーブルでのみ利用できます。
ClickHouse は、複数のカタログ (Unity、Glue、REST、Polaris など) とのインテグレーションをサポートしています。このガイドでは、ClickHouse と SeaweedFS カタログを使用してデータをクエリする手順を説明します。 SeaweedFS は、S3 互換ゲートウェイを備えたオープンソースの分散ファイル/オブジェクトストアです。S3 Table Buckets は、Iceberg デプロイメントを構成する両方の要素を提供します。埋め込みの Iceberg REST カタログがテーブルのメタデータを提供し、テーブルバケットが同じ S3 エンドポイントを介してテーブルデータを Parquet ファイルとして保存します。
  • 単一サービス - カタログのメタデータと Parquet データを単一のプロセスで提供し、別途メタデータデータベースは必要ありません
  • Iceberg REST カタログ仕様に準拠した REST API
  • サーバー側のメンテナンス - 外部のメンテナンスサービスを使用せずに、Parquet の自動コンパクションとスナップショットの期限切れ処理を行います
この機能は実験的であるため、次の設定で有効にする必要があります。 SET allow_experimental_database_iceberg = 1;

ローカル開発環境のセットアップ

ローカルでの開発・テストには、Docker Compose を使用して SeaweedFS と ClickHouse を実行できます。この方法は、学習、プロトタイピング、開発環境に適しています。

前提条件

  1. Docker および Docker Compose: Docker がインストールされ、起動していることを確認します
  2. バージョン: SeaweedFS 4.42 以降、ClickHouse 26.8 以降 (25.8 以降のバージョンでも読み取りと挿入は可能ですが、カタログを介したテーブルの作成には 26.8 が必要です)
  3. PyIceberg を含む Python (任意) : 以下でサンプルデータをシードするために使用します

ローカル SeaweedFS カタログのセットアップ

ステップ 1: この例を実行するための新しいフォルダを作成し、S3 ゲートウェイとカタログの認証情報を記載した s3config.json ファイルを作成します。
ステップ 2: 次の設定で docker-compose.yml ファイルを作成します。
mini コマンドは、SeaweedFS スタック全体を単一のコンテナー内で起動します。-tableBucket=analytics フラグは、Iceberg のwarehouseとして使用する、analytics という名前の S3 Tables バケットを事前に作成します。 ステップ 3: 次のコマンドを実行してサービスを起動します。

サンプルデータの投入

カタログは最初は空です。PyIceberg (pip install pyiceberg pyarrow) を使用してテーブルを作成し、数行を追加します。

ローカルの SeaweedFS カタログへの接続

ClickHouse コンテナーに接続します。
次に、SeaweedFS カタログへのデータベース接続を作成します。
エンジン引数には、ClickHouse がテーブルデータの読み取りに使用する S3 認証情報を指定します。一方、catalog_credentialoauth_server_uri は、OAuth2 のクライアント認証情報フローを通じてカタログ自体への認証に使用します。SeaweedFS では、どちらにも同じアクセスキーとシークレットキーを使用できます。

ClickHouse を使用して SeaweedFS カタログテーブルをクエリする

接続が確立されたら、SeaweedFS カタログ経由でクエリを実行できます。例:
バッククォートが必要ですClickHouse は複数のネームスペースをサポートしていないため、バッククォートが必要です。
テーブルをクエリするには:

ClickHouse からテーブルを作成し、データを書き込む

SeaweedFS カタログ内にテーブルを作成し、ClickHouse から直接データを書き込むこともできます。
IcebergS3 エンジン句では新しいテーブルのストレージパスを指定し、write_full_path_in_iceberg_metadata により、ClickHouse はテーブルの完全な場所をカタログに登録します。
カタログを介したテーブルの作成には、ClickHouse 26.8 以降が必要です。バージョン 26.4~26.7 では、ネームスペースを登録する前にテーブルファイルが書き込まれますが、ネームスペースがすでにカタログに存在しない限り、SeaweedFS はこれを拒否します。26.4 より前のバージョンでは成功したように見えますが、テーブルファイルはカタログに登録されないままオブジェクトストレージに書き込まれます。
ClickHouse が insert をコミットすると、SeaweedFS カタログは、実験的な writer がまだ生成しないメタデータを修復します。具体的には、manifest 内で欠落しているフィールド ID を補完し、bucket 相対のファイルパスを絶対ロケーションに書き換え、テーブルにデフォルトの名前マッピングを設定します。その後、PyIceberg や Spark などの厳密な reader は、ClickHouse が書き込んだ行を読み取れるようになります。これには SeaweedFS 4.42 以降が必要です。

データレイクから ClickHouse へのデータの読み込み

SeaweedFS カタログから ClickHouse にデータを読み込むには、まずローカルの ClickHouse テーブルを作成します。
次に、INSERT INTO SELECT を使用して、SeaweedFS カタログテーブルからデータを読み込みます。
最終更新日 2026年8月16日