メインコンテンツへスキップ

​
dbt-clickhouse アダプター

dbt (data build tool) を使うと、分析エンジニアは select 文を記述するだけで、データウェアハウス内のデータを変換できます。dbt は、これらの select 文をデータベース内のテーブルやビューといったオブジェクトとしてマテリアライズし、Extract Load and Transform (ELT) の T を担います。SELECT ステートメントで定義された モデル を作成できます。 dbt では、これらの モデル を相互参照したりレイヤー化したりすることで、より高水準の概念を構築できます。モデル 同士を接続するために必要な定型 SQL は自動的に生成されます。さらに、dbt は モデル 間の依存関係を特定し、有向非巡回グラフ (DAG) を使って適切な順序で作成されるようにします。 dbt は、ClickHouse がサポートするアダプター を通じて ClickHouse に対応しています。

​
サポートされている機能

サポートされている機能の一覧:
  • テーブルのマテリアライゼーション
  • ビューのマテリアライゼーション
  • 増分マテリアライゼーション
  • Microbatch 増分マテリアライゼーション
  • materialized view マテリアライゼーション (MATERIALIZED VIEW の TO 形式を使用、実験的)
  • シード
  • ソース
  • Docs の生成
  • テスト
  • スナップショット
  • ほとんどの dbt-utils マクロ (現在は dbt-core に含まれています)
  • Ephemeral マテリアライゼーション
  • 分散テーブルのマテリアライゼーション (実験的)
  • 分散増分マテリアライゼーション (実験的)
  • コントラクト
  • ClickHouse 固有のカラム設定 (Codec、有効期限 (TTL)…)
  • ClickHouse 固有のテーブル設定 (索引、プロジェクション…)
dbt-core 1.10 までのすべての機能をサポートしており、--sample フラグや、今後のリリースに向けたすべての非推奨警告への対応も含まれます。dbt 1.10 で導入された カタログインテグレーション (例: Iceberg) は、アダプターではまだネイティブサポートされていませんが、回避策は利用できます。詳しくは カタログサポートのセクション を参照してください。 このアダプターはまだ dbt Cloud では利用できませんが、近日中に利用可能になる見込みです。詳細については、サポートにお問い合わせください。

​
dbtの概念とサポートされているマテリアライゼーション

dbtでは、モデルという概念が導入されています。モデルはSQLステートメントとして定義され、複数のテーブルを結合することもあります。モデルは複数の方法で「マテリアライズ」できます。マテリアライゼーションは、モデルのselectクエリに対するbuild戦略を表します。マテリアライゼーションの実装は定型的なSQLで、SELECTクエリをステートメントで包み、新しいrelationを作成したり既存のrelationを更新したりします。 dbtは5種類のマテリアライゼーションを提供しており、これらはすべてdbt-clickhouseでサポートされています。
  • view (デフォルト): モデルはデータベース内のviewとしてbuildされます。ClickHouseでは、これはviewとしてbuildされます。
  • table: モデルはデータベース内のtableとしてbuildされます。ClickHouseでは、これはtableとしてbuildされます。
  • ephemeral: モデルはデータベース内に直接buildされず、代わりに依存先のモデルにCTE (Common Table Expressions) として取り込まれます。
  • incremental: モデルは最初にtableとしてマテリアライズされ、その後の実行ではdbtが新しい行をtableにinsertし、変更された行を更新します。
  • materialized view: モデルはデータベース内のmaterialized viewとしてbuildされます。ClickHouseでは、これはmaterialized viewとしてbuildされます。
追加の構文や句によって、基になるデータが変更された場合にこれらのモデルをどのように更新するかが定義されます。dbtでは一般に、パフォーマンスが問題になるまではviewマテリアライゼーションから始めることが推奨されています。tableマテリアライゼーションは、ストレージ使用量の増加と引き換えに、モデルのクエリ結果をtableとして保持することで、クエリ時のパフォーマンスを向上させます。incrementalアプローチはこれをさらに発展させたもので、基になるデータの以降の更新をターゲットテーブルに反映できるようにします。 ClickHouse向けの現在のアダプターは、dictionary、分散テーブル、distributed incremental のマテリアライゼーションもサポートしています。また、このアダプターはdbtのスナップショットおよびseedsもサポートしています。 以下は、dbt-clickhouseにおける実験的機能です。

​
dbt と ClickHouse アダプターのセットアップ

​
dbt-core と dbt-clickhouse のインストール

dbt では、コマンドラインインターフェイス (CLI) のインストール方法がいくつか用意されており、詳しくはこちらを参照してください。dbt と dbt-clickhouse の両方のインストールには、pip の使用を推奨します。

​
dbt に ClickHouse インスタンスの接続情報を設定します。

~/.dbt/profiles.yml ファイルで clickhouse-service プロファイルを設定し、スキーマ、ホスト、ポート、ユーザー、パスワードの各プロパティを指定します。接続設定オプションの一覧は、機能と構成 ページで確認できます。

​
dbt プロジェクトを作成する

これで、この profile を既存のプロジェクトで使用することも、次のコマンドで新しいプロジェクトを作成することもできます。
project_name ディレクトリ内で、ClickHouseサーバーに接続するためのプロファイル名を指定するよう、dbt_project.yml ファイルを更新します。

​
接続をテストする

CLI ツールで dbt debug を実行し、dbt が ClickHouse に接続できることを確認します。応答に Connection test: [OK connection ok] が含まれていれば、接続は成功しています。 dbt で ClickHouse を使用する方法の詳細については、ガイドページを参照してください。

​
モデルのテストとデプロイ (CI/CD)

dbt プロジェクトのテストとデプロイには、さまざまな方法があります。dbt では、ベストプラクティスのワークフロー や CI ジョブ に関する推奨事項を紹介しています。ここではいくつかの戦略を取り上げますが、これらは具体的なユースケースに合わせて大きく調整する必要がある場合がある点に留意してください。

​
シンプルなデータテストと単体テストを使った CI/CD

CI パイプラインを手軽に立ち上げる方法の 1 つは、ジョブ内で ClickHouse クラスターを実行し、それに対してモデルを実行することです。モデルの実行前に、このクラスターへデモデータを挿入できます。本番データの一部を seed を使ってステージング環境に投入するだけでも十分です。 データを挿入したら、data tests と unit tests を実行できます。 CD ステップは、本番の ClickHouse クラスターに対して dbt build を実行するだけのシンプルなものにもできます。

​
より完全な CI/CD ステージ: 新しいデータを使用し、影響を受けるモデルのみをテストする

一般的な戦略の 1 つは、Slim CI ジョブを使用することです。この場合、変更されたモデル (およびその上流・下流の依存関係) のみを再デプロイします。このアプローチでは、本番実行のアーティファクト (つまり dbt manifest) を使用して、プロジェクトの実行時間を短縮し、環境間でスキーマドリフトが発生しないようにします。 開発環境の同期を保ち、古いデプロイ先に対してモデルを実行してしまうのを避けるために、clone や defer を使用できます。 本番環境の運用に影響を与えないようにするため、テスト環境 (つまりステージング環境) には専用の ClickHouse クラスターまたはサービスを使用することを推奨します。テスト環境を実運用に近いものにするには、本番データの一部を使用することに加え、環境間でスキーマドリフトが起きない形で dbt を実行することが重要です。
  • テスト対象として新しいデータが不要な場合は、本番データのバックアップをステージング環境に復元できます。
  • テスト対象として新しいデータが必要な場合は、remoteSecure() table function とリフレッシュ可能なマテリアライズドビューを組み合わせて使用し、必要な頻度で挿入できます。もう 1 つの方法は、オブジェクトストレージを中間ストレージとして使用し、本番サービスから定期的にデータを書き出してから、オブジェクトストレージの table function または ClickPipes (継続的インジェスト用) を使ってステージング環境に取り込むことです。
CI テスト用に専用環境を使用すると、本番環境に影響を与えずに手動テストを行うこともできます。たとえば、テストのために BI ツールの接続先をこの環境に向けることができます。 デプロイメント (つまり CD のステップ) については、本番デプロイメントのアーティファクトを使用して、変更されたモデルだけを更新することを推奨します。そのためには、dbt アーティファクト用の中間ストレージとしてオブジェクトストレージ (例: S3) を設定する必要があります。設定後は、dbt build --select state:modified+ --state path/to/last/deploy/state.json のようなコマンドを実行することで、本番での前回実行以降の変更内容に基づき、必要最小限のモデルだけを選択的に再ビルドできます。

​
よくある問題の対処法

​
接続

dbt から ClickHouse への接続で問題が発生した場合は、次の条件を満たしていることを確認してください。
  • エンジンは、サポートされているエンジン のいずれかである必要があります。
  • データベースにアクセスするための十分な権限が必要です。
  • データベースのデフォルトのテーブルエンジンを使用していない場合は、モデルの設定でテーブルエンジンを指定する必要があります。

​
長時間実行される操作を理解する

特定の ClickHouse クエリが原因で、一部の操作は想定より長くかかることがあります。どのクエリに時間がかかっているのかを詳しく把握するには、ログレベルを debug に上げてください。これにより、各クエリの実行時間が出力されます。たとえば、dbt コマンドに --log-level debug を追加すると有効にできます。

​
制限事項

現在の dbt 用 ClickHouse アダプターには、いくつか注意すべき制限があります。
  • このプラグインは、ClickHouse バージョン 25.3 以降が必要な構文を使用しています。ClickHouse の旧バージョンはテストしていません。また、現時点ではレプリケートテーブルもテスト対象外です。
  • dbt-adapter を同時に実行すると競合が発生する可能性があります。内部的に、同じ操作に対して同じテーブル名を使うことがあるためです。詳細は issue #420 を参照してください。
  • このアダプターは現在、INSERT INTO SELECT を使って モデル をテーブルとして materialize します。つまり、再度実行すると実質的にデータが重複します。非常に大規模な datasets (PB 単位) では実行時間が極端に長くなり、一部の モデル は現実的でなくなる可能性があります。パフォーマンスを改善するには、view を materialized: materialization_view として実装し、ClickHouse Materialized Views を使用してください。さらに、可能な場合は GROUP BY を活用して、各クエリが返す行数をできるだけ少なくしてください。ソースと同じ行数を保ったまま単に変換する モデル よりも、データを要約する モデル を優先してください。
  • モデル を表すために分散テーブルを使用する場合、基盤となるレプリケートテーブルを各ノードで手動作成する必要があります。その上に分散テーブルを作成できます。アダプターはクラスターの作成を管理しません。
  • dbt がデータベース内に relation (table/view) を作成する場合、通常は {{ database }}.{{ schema }}.{{ table/view id }} として作成します。ClickHouse には schema の概念がありません。そのため、このアダプターでは {{schema}}.{{ table/view id }} を使用します。ここでの schema は ClickHouse の database を指します。
  • ephemeral モデル/CTE は、ClickHouse の insert ステートメントで INSERT INTO より前に置くと動作しません。https://github.com/ClickHouse/ClickHouse/issues/30323 を参照してください。これはほとんどの モデル には影響しないはずですが、モデル 定義やその他の SQL ステートメントで ephemeral モデル をどこに配置するかには注意が必要です。

​
Fivetran

dbt-clickhouse コネクタは、Fivetran transformations でも利用でき、dbt を使用して Fivetran プラットフォーム内でシームレスにインテグレーションと変換を行えます。
最終更新日 2026年6月12日