dbt Slim CI実践ガイド: state:modified+ で差分だけ安全に流す

本稿は、dbtのSlim CIを「state:modified+」で実装し、プルリクエスト（PR）で変化したモデルとその下流だけを素早く検証するための実務ガイドです。

Analytics Engineer認定でも頻出の、state選択・defer・アーティファクト運用の要点を、現場の落とし穴とあわせて解説します。

Slim CIの狙いと全体像

Slim CIは、前回の安定状態（本番のアーティファクト）と比較して変更が入った対象のみをCIで実行し、レビューを高速化する手法です。dbtでは state:modified を選択子に使い、さらに + を付けて下流も含めることで、影響範囲の検証を短時間に絞り込みます。

Slim CIの核は「前回の状態」を示すアーティファクト（典型的には本番のmanifest.json）です。CIはこれを --state オプションで読み込み、ローカルの変更点と比較します。実行時には --defer を併用し、選択外の参照先は本番に委譲します。これにより、変更していない上流をCIで再作成せずに、テストを正しく実行できます。

• state:modified+ は「変更されたノードとその下流」を選択
• --state は比較元（本番のmanifest.jsonなど）を指定
• --defer は未選択ノードの参照解決を本番アーティファクトに委譲
• dbt build を使うとモデル・スナップショット・シード・テストまで一括実行

Slim CIのデータフロー（概念図）

PRブランチ                 CIランナー                     本番（前回成功状態）
    |  変更 (SQL/モデル)         |                                 |
    |--------------------------->| 1. 本番の manifest.json 取得     |
    |                            |<---------------------------------|
    |                            | 2. dbt build -s state:modified+ --defer --state=./state
    |                            |    ├─ 変更ノードを選択
    |                            |    ├─ 下流も含めて実行/テスト
    |                            |    └─ 未選択の参照は本番に委譲
    |                            |                                 |
    |<---------------------------| 3. 結果（成功/失敗・アーティファクト）

state:modified+ の仕組みと周辺オプション

state:modified は、--state で指す過去のアーティファクト（一般に manifest.json）と現在のプロジェクト定義を比較し、差分があるノードを選びます。差分には、SQLやschemaファイルの定義変更、新規追加、パスやconfigの変更などが含まれます。末尾の + は、選択されたノードの子孫（下流）も含める指定です。

Slim CIではこれに --defer を組み合わせます。--defer は、選択されなかったref()/source()解決を --state のリレーションに委譲し、未変更の上流をCIで再作成しないようにします。これにより、テストも本番データを参照して成立します。

• dbt ls -s state:modified+ で対象一覧を事前確認できる
• 新規ノードは state:new で明示選択も可能（例: dbt build -s state:new+）
• --indirect-selection=eager を付与すると、関連テストの取りこぼしを抑制しやすい
• アーティファクト比較はファイル内容・依存情報を基に行われるため、単純なタイムスタンプ比較ではない

実装手順（GitHub Actions + dbt Coreの例）

本番で成功したパイプラインから manifest.json（必要に応じて run_results.json も）を成果物として保存し、PRのCIで取得します。CIはそのアーティファクトを --state に指定し、--defer を有効化して差分のみを実行します。

SnowflakeやDatabricksなどの接続情報はリポジトリシークレットで注入します。並列実行やキャッシュは環境に合わせて調整してください。

• mainブランチ成功時に target/ 配下をアーティファクト化（少なくとも manifest.json）
• PR CIでそのアーティファクトをダウンロードし、--state で参照
• dbt build -s state:modified+ --defer --indirect-selection=eager を実行
• 必要に応じて dbt ls で対象をログに出し、選択の妥当性をレビュー可能化

GitHub Actions（抜粋）

name: pr-slim-ci
on:
  pull_request:
    branches: [ main ]
jobs:
  slim-ci:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dbt
        run: |
          pip install --upgrade pip
          pip install dbt-core dbt-snowflake  # 使うアダプタに合わせて変更

      - name: Download prod artifacts
        uses: actions/download-artifact@v4
        with:
          name: prod-target-artifacts
          path: state/

      - name: Show planned selection
        run: |
          dbt --version
          dbt deps
          dbt ls -s 'state:modified+' --state state | tee selection.txt

      - name: Slim CI build
        env:
          DBT_PROFILES_DIR: ./.profiles  # 適宜
          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}
          SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}
          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
        run: |
          dbt build -s 'state:modified+' \
            --defer --state state \
            --indirect-selection=eager \
            --target ci

      - name: Upload CI artifacts
        uses: actions/upload-artifact@v4
        with:
          name: pr-ci-target
          path: target/

よくある落とし穴と検証ポイント

アーティファクトの取り違えは最大の落とし穴です。PRブランチで直前に生成したmanifest.jsonを --state に渡すと、差分が検出されず、意図せず未検証となることがあります。必ず「本番で最後に成功した」アーティファクトを使います。

マクロやパッケージの変更は、モデルに影響する場合があります。state比較は依存関係も見ているため、多くのケースで変更が伝播しますが、レビューでは dbt ls の結果を確認し、テストの取りこぼしがないかを見るのが安全です。

• --state は本番のmanifest.jsonを指すこと。PR生成物を参照しない
• --defer を忘れると、未選択の上流までCIで再作成してしまい、時間/コストが膨張
• ソース定義や契約（contracts）変更は下流の再検証が必要。state:modified+ で捕捉されるか ls で確認
• シードやスナップショット変更は build に含まれるが、選択漏れがないか注意
• 間接選択は明示的に --indirect-selection=eager を推奨（関連テストの網羅性向上）

本番アーティファクトの保管とセキュリティ

manifest.json はモデル定義やリレーション名などのメタデータを含みます。一般にPIIは含みませんが、スキーマ名・テーブル名などの内部情報は含まれるため、公開範囲を制御し、リポジトリアクセス権限を適切に設計します。

保存場所はCI/CDのビルドアーティファクト、オブジェクトストレージ、もしくはdbt Cloudの前回ランからの取得などが一般的です。アーティファクトのライフサイクル（保持期間、ローテーション）を決め、必ず最後に成功したバージョンを参照できるようにします。

• 最小権限のストレージに保存し、PRから読み取り専用で取得
• アーティファクト名やパスは固定化し、取り違えを防止
• 保持期間はリリースサイクルに合わせて設定（例: 30〜90日）
• dbt Cloud利用時は前回成功ランのArtifacts API活用を検討

試験対策チェックリスト（Analytics Engineer）

試験では、変更のあるモデルとその下流のみをCIで実行する最適解を選ばせる設問がよく出ます。state:modified+ と --defer の組み合わせをキーワードとして押さえ、--state で参照するアーティファクトが「本番の前回成功状態」である点を明言できるようにしましょう。

選択子の違い、build と run の使い分け、ソースやシード・スナップショットの扱いも要確認です。

• state:modified と state:new の違いを説明できる
• + の意味（子孫選択）を説明できる
• --defer の効果を説明できる（未選択のref/source解決を本番に委譲）
• dbt build はモデル・シード・スナップショット・テストを包括実行
• dbt ls で選択結果を検証できる

問題で確認

よくある質問