クイックリファレンス

dbt Core のインストールと初期化

# pip でインストール（BigQueryアダプター例）
pip install dbt-bigquery

# その他のアダプター
pip install dbt-snowflake
pip install dbt-redshift
pip install dbt-postgres

# プロジェクト初期化
dbt init my_project
cd my_project

# 接続テスト
dbt debug

プロジェクト構造

my_project/
├── dbt_project.yml       # プロジェクト設定
├── profiles.yml          # DB接続設定（~/.dbt/profiles.yml が標準）
├── models/
│   ├── staging/          # 生データの整形層
│   │   └── stg_orders.sql
│   └── marts/            # 分析用の集計層
│       └── fct_orders.sql
├── tests/                # カスタムテスト
└── macros/               # 再利用可能なJinja2関数

モデルの書き方

-- models/staging/stg_orders.sql
SELECT
    order_id,
    customer_id,
    CAST(order_date AS DATE) AS order_date,
    amount
FROM {{ source('raw', 'orders') }}  -- ソース定義を参照
WHERE amount > 0

-- models/marts/fct_monthly_sales.sql
SELECT
    DATE_TRUNC(order_date, MONTH) AS month,
    COUNT(*) AS order_count,
    SUM(amount) AS total_amount
FROM {{ ref('stg_orders') }}        -- 他モデルを参照
GROUP BY 1

schema.yml（テスト・ドキュメント定義）

version: 2

models:
  - name: stg_orders
    description: "受注テーブルの整形済みStaging層"
    columns:
      - name: order_id
        description: "受注ID"
        tests:
          - unique
          - not_null
      - name: amount
        tests:
          - not_null

主要コマンド

dbt run              # モデルを実行（テーブル/ビュー作成）
dbt test             # データ品質テスト実行
dbt build            # run + test を一括実行（CI向け）
dbt docs generate    # ドキュメントサイト生成
dbt docs serve       # ドキュメントをローカルで確認
dbt run --select stg_orders   # 特定モデルのみ実行

---

よくある詰まりポイント

Q. dbt run でモデルが実行されるが空のテーブルができる

A. SQLのWHERE句の条件や source() 参照のスキーマ名を確認してください。dbt debug で接続設定が正しいか確認し、dbt compile で実際に実行されるSQLを target/compiled/ フォルダで確認するとデバッグしやすいです。

Q. {{ ref('model_name') }} で参照しているのにエラーになる

A. 参照先のモデルファイル名（.sql の拡張子を除いた部分）と ref() 内の文字列が完全一致しているか確認してください。フォルダ階層は関係なく、プロジェクト内でユニークなモデル名を使います。同名モデルが複数存在するとエラーになります。

Q. dbt test でuniqueness testが失敗する

A. 実際にデータに重複があるケースが多いです。SELECT カラム, COUNT(*) FROM テーブル GROUP BY 1 HAVING COUNT(*) > 1 で重複データを確認してください。想定外の重複があればソースデータの品質問題なので、Staging層で QUALIFY ROW_NUMBER() OVER (PARTITION BY id ORDER BY updated_at DESC) = 1 のように重複除去する処理を追加しましょう。