はじめに
この記事では、dbt（data build tool）の基本的なコマンドを初学者向けにまとめています。
「dbtを触り始めたけど、どのコマンドから覚えればいいかわからない」という方を対象に、各コマンドの役割と使い方を整理しました。
本記事は dbt Core（CLI版） を前提としています。dbt Cloudをお使いの場合はGUI上で同等の操作が可能です。
dbtとは
dbtは、データウェアハウス上でのデータ変換（Transform）に特化したツールです。ELTパイプラインの「T」を担当し、SQLベースでデータモデルの定義・テスト・ドキュメント生成を一元管理できます。
dbtを使うことで、以下のようなメリットがあります。
- SQLを書くだけでデータ変換パイプラインを構築できる
- モデル間の依存関係を自動で解決してくれる
- テストやドキュメントをコードと一緒に管理できる
- Gitでバージョン管理ができる
環境セットアップ系コマンド
dbt init
新しいdbtプロジェクトを作成するコマンドです。プロジェクト名を指定すると、ディレクトリ構成やサンプルファイルが自動生成されます。
# 新しいプロジェクトを作成
dbt init my_project
実行すると、以下のようなディレクトリ構成が作られます。
my_project/
├── models/
│ └── example/
├── tests/
├── macros/
├── seeds/
├── snapshots/
├── dbt_project.yml
└── README.md
初回実行時には、接続先のデータウェアハウス（BigQuery、Snowflakeなど）の情報を対話形式で入力します。設定は ~/.dbt/profiles.yml に保存されます。
dbt debug
dbtの接続設定やプロジェクト設定が正しいかを確認するコマンドです。環境構築後に最初に実行しておくと安心です。
dbt debug
主に以下の項目がチェックされます。
-
profiles.ymlの存在と設定内容 -
dbt_project.ymlの存在と設定内容 - データウェアハウスへの接続可否
モデルの実行系コマンド
dbt run
定義したSQLモデルをデータウェアハウス上で実行（マテリアライズ）するコマンドです。dbtで最もよく使うコマンドと言えます。
# すべてのモデルを実行
dbt run
dbt run --select
特定のモデルだけを指定して実行したい場合は、--select（短縮形: -s）オプションを使います。
# 特定のモデルのみ実行
dbt run --select my_model
# 特定のディレクトリ配下のモデルをすべて実行
dbt run --select staging.*
--select はモデルが増えてきたときに非常に重要になります。全モデル実行は時間がかかるため、開発中は対象を絞って実行する習慣をつけましょう。
dbt run --full-refresh
インクリメンタルモデル（materialized='incremental'）を使用している場合、通常の dbt run では差分のみが処理されます。テーブルを一から作り直したい場合に --full-refresh を使います。
dbt run --full-refresh
テスト系コマンド
dbt test
schema.yml で定義したテスト（not_null、unique、accepted_values など）や、tests/ ディレクトリに配置したカスタムテストを実行します。
# すべてのテストを実行
dbt test
テストの定義例（schema.yml）は以下のようになります。
version: 2
models:
- name: customers
columns:
- name: customer_id
tests:
- not_null
- unique
- name: status
tests:
- accepted_values:
values: ['active', 'inactive', 'pending']
dbt test --select
dbt run と同様に、特定のモデルに関連するテストだけを実行できます。
# 特定モデルのテストのみ実行
dbt test --select my_model
ドキュメント系コマンド
dbt docs generate
プロジェクト内のモデル定義や schema.yml の記述をもとに、ドキュメントサイト用のJSONファイルを生成します。
dbt docs generate
dbt docs serve
生成したドキュメントをローカルサーバーで閲覧できるようにするコマンドです。ブラウザで自動的にドキュメントサイトが開きます。
dbt docs serve
ドキュメントサイトでは、モデル間の依存関係を示す Lineage Graph（リネージグラフ） を確認できます。データの流れを視覚的に把握できるため、非常に便利です。
その他よく使うコマンド
dbt seed
CSVファイルをデータウェアハウスにテーブルとしてロードします。マスタデータやテスト用のデータを投入したいときに便利です。
dbt seed
CSVファイルは seeds/ ディレクトリに配置します。
seeds/
└── country_codes.csv
dbt snapshot
Slowly Changing Dimension（SCD Type 2）を実現するためのコマンドです。ソーステーブルの履歴変更を追跡できます。
dbt snapshot
dbt source freshness
ソースデータの鮮度をチェックします。sources.yml で定義した loaded_at_field と freshness の設定に基づいて、データが最新かどうかを判定します。
dbt source freshness
dbt clean
dbtが生成した一時ファイル（target/ や dbt_packages/ など）を削除します。キャッシュが原因で問題が起きた場合に使います。
dbt clean
dbt compile
SQLモデルをJinjaテンプレートから実際のSQLに変換しますが、データウェアハウスには実行しません。生成されるSQLを確認したい場合に使います。
dbt compile
コンパイル結果は target/compiled/ ディレクトリに出力されます。デバッグ時にとても役立ちます。
知っておくと便利なオプション・Tips
dbt build — run + test をまとめて実行
dbt build は run・test・seed・snapshot を依存関係の順番に沿ってまとめて実行するコマンドです。CI/CDパイプラインで特に重宝します。
dbt build
ノード選択構文
--select オプションでは、以下のような構文でモデルの選択範囲を柔軟に指定できます。
| 構文 | 意味 | 例 |
|---|---|---|
model_name |
指定モデルのみ | dbt run -s my_model |
+model_name |
指定モデルとその上流すべて | dbt run -s +my_model |
model_name+ |
指定モデルとその下流すべて | dbt run -s my_model+ |
+model_name+ |
上流・下流すべて | dbt run -s +my_model+ |
tag:my_tag |
特定タグのモデル | dbt run -s tag:daily |
path/to/models |
ディレクトリ指定 | dbt run -s staging.* |
--target によるターゲット切り替え
profiles.yml に複数のターゲット（dev, prod など）を定義しておくことで、実行環境を切り替えられます。
# 本番環境で実行
dbt run --target prod
まとめ
本記事で紹介した基本コマンドを一覧にまとめます。
| コマンド | 用途 |
|---|---|
dbt init |
プロジェクトの新規作成 |
dbt debug |
接続設定の確認 |
dbt run |
モデルの実行 |
dbt test |
テストの実行 |
dbt docs generate |
ドキュメントの生成 |
dbt docs serve |
ドキュメントの閲覧 |
dbt seed |
CSVデータのロード |
dbt snapshot |
スナップショットの取得 |
dbt source freshness |
ソースの鮮度チェック |
dbt clean |
一時ファイルの削除 |
dbt compile |
SQLのコンパイル（実行なし） |
dbt build |
run + test + seed + snapshot の一括実行 |
まずは dbt init → dbt debug → dbt run → dbt test の流れを一通り試してみるのがおすすめです。慣れてきたら --select や dbt build を活用して、効率的な開発フローを構築していきましょう。
最後まで読んでいただきありがとうございました。この記事が参考になりましたら、ぜひLGTMをお願いします。