> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > dbt を使用して、ClickHouse でデータの変換とモデリングを行えます # dbt と ClickHouse の連携 export const ClickHouseSupportedBadge = () => { return
ClickHouse対応
; };
## dbt-clickhouse アダプター
**dbt** (data build tool) を使うと、分析エンジニアは `select` 文を記述するだけで、データウェアハウス内のデータを変換できます。dbt は、これらの `select` 文をデータベース内のテーブルやビューといったオブジェクトとしてマテリアライズし、[Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform) の T を担います。SELECT ステートメントで定義された モデル を作成できます。 dbt では、これらの モデル を相互参照したりレイヤー化したりすることで、より高水準の概念を構築できます。モデル 同士を接続するために必要な定型 SQL は自動的に生成されます。さらに、dbt は モデル 間の依存関係を特定し、有向非巡回グラフ (DAG) を使って適切な順序で作成されるようにします。 dbt は、[ClickHouse がサポートするアダプター](https://github.com/ClickHouse/dbt-clickhouse) を通じて ClickHouse に対応しています。 | ページ | 説明 | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | [機能と構成](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | 利用可能な機能と一般的な構成の説明 | | [マテリアライゼーション](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | 利用可能なマテリアライゼーションとその構成 | | [Materialized views](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | materialized\_view マテリアライゼーションの個別ドキュメント | | [ガイド](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | ClickHouse で dbt を使用するためのガイド |
## サポートされている機能
サポートされている機能の一覧: * [x] テーブルのマテリアライゼーション * [x] ビューのマテリアライゼーション * [x] 増分マテリアライゼーション * [x] Microbatch 増分マテリアライゼーション * [x] materialized view マテリアライゼーション (MATERIALIZED VIEW の `TO` 形式を使用、実験的) * [x] シード * [x] ソース * [x] Docs の生成 * [x] テスト * [x] スナップショット * [x] ほとんどの dbt-utils マクロ (現在は dbt-core に含まれています) * [x] Ephemeral マテリアライゼーション * [x] 分散テーブルのマテリアライゼーション (実験的) * [x] 分散増分マテリアライゼーション (実験的) * [x] コントラクト * [x] ClickHouse 固有のカラム設定 (Codec、有効期限 (TTL)...) * [x] ClickHouse 固有のテーブル設定 (索引、プロジェクション...) dbt-core 1.10 までのすべての機能をサポートしており、`--sample` フラグや、今後のリリースに向けたすべての非推奨警告への対応も含まれます。dbt 1.10 で導入された **カタログインテグレーション** (例: Iceberg) は、アダプターではまだネイティブサポートされていませんが、回避策は利用できます。詳しくは [カタログサポートのセクション](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support) を参照してください。 このアダプターはまだ [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview) では利用できませんが、近日中に利用可能になる見込みです。詳細については、サポートにお問い合わせください。
## dbtの概念とサポートされているマテリアライゼーション
dbtでは、モデルという概念が導入されています。モデルはSQLステートメントとして定義され、複数のテーブルを結合することもあります。モデルは複数の方法で「マテリアライズ」できます。マテリアライゼーションは、モデルのselectクエリに対するbuild戦略を表します。マテリアライゼーションの実装は定型的なSQLで、`SELECT`クエリをステートメントで包み、新しいrelationを作成したり既存のrelationを更新したりします。 dbtは5種類のマテリアライゼーションを提供しており、これらはすべて`dbt-clickhouse`でサポートされています。 * **view** (デフォルト): モデルはデータベース内のviewとしてbuildされます。ClickHouseでは、これは[view](/docs/ja/reference/statements/create/view)としてbuildされます。 * **table**: モデルはデータベース内のtableとしてbuildされます。ClickHouseでは、これは[table](/docs/ja/reference/statements/create/table)としてbuildされます。 * **ephemeral**: モデルはデータベース内に直接buildされず、代わりに依存先のモデルにCTE (Common Table Expressions) として取り込まれます。 * **incremental**: モデルは最初にtableとしてマテリアライズされ、その後の実行ではdbtが新しい行をtableにinsertし、変更された行を更新します。 * **materialized view**: モデルはデータベース内のmaterialized viewとしてbuildされます。ClickHouseでは、これは[materialized view](/docs/ja/reference/statements/create/view#materialized-view)としてbuildされます。 追加の構文や句によって、基になるデータが変更された場合にこれらのモデルをどのように更新するかが定義されます。dbtでは一般に、パフォーマンスが問題になるまではviewマテリアライゼーションから始めることが推奨されています。tableマテリアライゼーションは、ストレージ使用量の増加と引き換えに、モデルのクエリ結果をtableとして保持することで、クエリ時のパフォーマンスを向上させます。incrementalアプローチはこれをさらに発展させたもので、基になるデータの以降の更新をターゲットテーブルに反映できるようにします。 ClickHouse向けの[現在のアダプター](https://github.com/silentsokolov/dbt-clickhouse)は、**dictionary**、**分散テーブル**、**distributed incremental** のマテリアライゼーションもサポートしています。また、このアダプターはdbtの[スナップショット](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy)および[seeds](https://docs.getdbt.com/docs/building-a-dbt-project/seeds)もサポートしています。 以下は、`dbt-clickhouse`における[実験的機能](/docs/ja/reference/settings/beta-and-experimental-features)です。 | 種類 | サポート状況 | 詳細 | | --------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Materialized View materialization | はい。明示的ターゲットでの作成はベータです | [materialized view](/docs/ja/reference/statements/create/view#materialized-view)を作成します。 | | 分散テーブル materialization | はい、Experimental | [分散テーブル](/docs/ja/reference/engines/table-engines/special/distributed)を作成します。 | | Distributed incremental materialization | はい、Experimental | 分散テーブルと同じ考え方に基づくincrementalモデルです。すべての戦略がサポートされているわけではない点に注意してください。詳細は[該当ドキュメントのセクション](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental)を参照してください。 | | Dictionary materialization | はい、Experimental | [Dictionary](/docs/ja/reference/engines/table-engines/special/dictionary)を作成します。 |
## dbt と ClickHouse アダプターのセットアップ
### dbt-core と dbt-clickhouse のインストール
dbt では、コマンドラインインターフェイス (CLI) のインストール方法がいくつか用意されており、詳しくは[こちら](https://docs.getdbt.com/dbt-cli/install/overview)を参照してください。dbt と dbt-clickhouse の両方のインストールには、`pip` の使用を推奨します。 ```sh theme={null} pip install dbt-core dbt-clickhouse ```
### dbt に ClickHouse インスタンスの接続情報を設定します。
`~/.dbt/profiles.yml` ファイルで `clickhouse-service` プロファイルを設定し、スキーマ、ホスト、ポート、ユーザー、パスワードの各プロパティを指定します。接続設定オプションの一覧は、[機能と構成](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) ページで確認できます。 ```yaml theme={null} clickhouse-service: target: dev outputs: dev: type: clickhouse schema: [ default ] # dbtモデル用のClickHouseデータベース # オプション host: [ localhost ] port: [ 8123 ] # secureおよびドライバー設定に応じて、デフォルトは8123、8443、9000、9440 user: [ default ] # すべてのデータベース操作に使用するユーザー password: [ ] # ユーザーのパスワード secure: True # TLS（ネイティブプロトコル）またはHTTPS（httpプロトコル）を使用 ```
### dbt プロジェクトを作成する
これで、この `profile` を既存のプロジェクトで使用することも、次のコマンドで新しいプロジェクトを作成することもできます。 ```sh theme={null} dbt init project_name ``` `project_name` ディレクトリ内で、ClickHouseサーバーに接続するためのプロファイル名を指定するよう、`dbt_project.yml` ファイルを更新します。 ```yaml theme={null} profile: 'clickhouse-service' ```
### 接続をテストする
CLI ツールで `dbt debug` を実行し、dbt が ClickHouse に接続できることを確認します。応答に `Connection test: [OK connection ok]` が含まれていれば、接続は成功しています。 dbt で ClickHouse を使用する方法の詳細については、[ガイドページ](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/guides)を参照してください。
### モデルのテストとデプロイ (CI/CD)
dbt プロジェクトのテストとデプロイには、さまざまな方法があります。dbt では、[ベストプラクティスのワークフロー](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) や [CI ジョブ](https://docs.getdbt.com/docs/deploy/ci-jobs) に関する推奨事項を紹介しています。ここではいくつかの戦略を取り上げますが、これらは具体的なユースケースに合わせて大きく調整する必要がある場合がある点に留意してください。
#### シンプルなデータテストと単体テストを使った CI/CD
CI パイプラインを手軽に立ち上げる方法の 1 つは、ジョブ内で ClickHouse クラスターを実行し、それに対してモデルを実行することです。モデルの実行前に、このクラスターへデモデータを挿入できます。本番データの一部を [seed](https://docs.getdbt.com/reference/commands/seed) を使ってステージング環境に投入するだけでも十分です。 データを挿入したら、[data tests](https://docs.getdbt.com/docs/build/data-tests) と [unit tests](https://docs.getdbt.com/docs/build/unit-tests) を実行できます。 CD ステップは、本番の ClickHouse クラスターに対して `dbt build` を実行するだけのシンプルなものにもできます。
#### より完全な CI/CD ステージ: 新しいデータを使用し、影響を受けるモデルのみをテストする
一般的な戦略の 1 つは、[Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci) ジョブを使用することです。この場合、変更されたモデル (およびその上流・下流の依存関係) のみを再デプロイします。このアプローチでは、本番実行のアーティファクト (つまり [dbt manifest](https://docs.getdbt.com/reference/artifacts/manifest-json)) を使用して、プロジェクトの実行時間を短縮し、環境間でスキーマドリフトが発生しないようにします。 開発環境の同期を保ち、古いデプロイ先に対してモデルを実行してしまうのを避けるために、[clone](https://docs.getdbt.com/reference/commands/clone) や [defer](https://docs.getdbt.com/reference/node-selection/defer) を使用できます。 本番環境の運用に影響を与えないようにするため、テスト環境 (つまりステージング環境) には専用の ClickHouse クラスターまたはサービスを使用することを推奨します。テスト環境を実運用に近いものにするには、本番データの一部を使用することに加え、環境間でスキーマドリフトが起きない形で dbt を実行することが重要です。 * テスト対象として新しいデータが不要な場合は、本番データのバックアップをステージング環境に復元できます。 * テスト対象として新しいデータが必要な場合は、[`remoteSecure()` table function](/docs/ja/reference/functions/table-functions/remote) とリフレッシュ可能なマテリアライズドビューを組み合わせて使用し、必要な頻度で挿入できます。もう 1 つの方法は、オブジェクトストレージを中間ストレージとして使用し、本番サービスから定期的にデータを書き出してから、オブジェクトストレージの table function または ClickPipes (継続的インジェスト用) を使ってステージング環境に取り込むことです。 CI テスト用に専用環境を使用すると、本番環境に影響を与えずに手動テストを行うこともできます。たとえば、テストのために BI ツールの接続先をこの環境に向けることができます。 デプロイメント (つまり CD のステップ) については、本番デプロイメントのアーティファクトを使用して、変更されたモデルだけを更新することを推奨します。そのためには、dbt アーティファクト用の中間ストレージとしてオブジェクトストレージ (例: S3) を設定する必要があります。設定後は、`dbt build --select state:modified+ --state path/to/last/deploy/state.json` のようなコマンドを実行することで、本番での前回実行以降の変更内容に基づき、必要最小限のモデルだけを選択的に再ビルドできます。
## よくある問題の対処法
### 接続
dbt から ClickHouse への接続で問題が発生した場合は、次の条件を満たしていることを確認してください。 * エンジンは、[サポートされているエンジン](/docs/ja/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines) のいずれかである必要があります。 * データベースにアクセスするための十分な権限が必要です。 * データベースのデフォルトのテーブルエンジンを使用していない場合は、モデルの設定でテーブルエンジンを指定する必要があります。
### 長時間実行される操作を理解する
特定の ClickHouse クエリが原因で、一部の操作は想定より長くかかることがあります。どのクエリに時間がかかっているのかを詳しく把握するには、[ログレベル](https://docs.getdbt.com/reference/global-configs/logs#log-level)を `debug` に上げてください。これにより、各クエリの実行時間が出力されます。たとえば、dbt コマンドに `--log-level debug` を追加すると有効にできます。
## 制限事項
現在の dbt 用 ClickHouse アダプターには、いくつか注意すべき制限があります。 * このプラグインは、ClickHouse バージョン 25.3 以降が必要な構文を使用しています。ClickHouse の旧バージョンはテストしていません。また、現時点ではレプリケートテーブルもテスト対象外です。 * `dbt-adapter` を同時に実行すると競合が発生する可能性があります。内部的に、同じ操作に対して同じテーブル名を使うことがあるためです。詳細は issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420) を参照してください。 * このアダプターは現在、[INSERT INTO SELECT](/docs/ja/reference/statements/insert-into#inserting-the-results-of-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](https://github.com/ClickHouse/ClickHouse/issues/30323) を参照してください。これはほとんどの モデル には影響しないはずですが、モデル 定義やその他の SQL ステートメントで ephemeral モデル をどこに配置するかには注意が必要です。 {/* TODO review this limitation, looks like the issue was already closed and the fix was introduced in 24.10 */}
## Fivetran
`dbt-clickhouse` コネクタは、[Fivetran transformations](https://fivetran.com/docs/transformations/dbt) でも利用でき、`dbt` を使用して Fivetran プラットフォーム内でシームレスにインテグレーションと変換を行えます。