dbt Model Versionsを使い切る: 破壊的変更を安全に届ける運用設計

dbtのモデル・バージョンは、破壊的変更を安全に段階展開するための公式機能です。明示的にvを付けて参照し、互換レイヤで消費者を段階的に切り替えることで、事故のないリリースと即時ロールバックを両立できます。

本稿は、試験対策の要点を押さえつつ、現場で迷いがちな切替順序や互換ビューの使い方までを具体的に解説します。記述はdbt公式ドキュメントの安定的な挙動に基づいています。

モデルにバージョンを付ける理由と全体像

分析用のモデルは長期的に参照されるため、列の削除や意味変更といった破壊的変更は避けられません。dbtのモデル・バージョンは、旧版と新版を並行稼働させ、消費側を計画的に切り替えるための仕組みを提供します。

基本方針はシンプルです。プロデューサ（上流）では新旧バージョンを同時に生成し、消費側は明示的に特定のバージョンへrefでピン留めします。外部公開名（安定名）は互換ビューで吸収し、切替時はビューの参照先だけを差し替えます。

• 破壊的変更を段階展開し、即時ロールバック可能にする
• 消費者ごとに移行タイミングを制御（ピン留め参照）
• スキーマ契約（contracts）と組み合わせて安全性を担保

併存と段階的切替の全体像

互換ビューの差し替え例（Snowflake/Databricksで共通的な考え方）

-- 安定名の互換ビューをv1からv2へ切替
-- 既存クエリは常に安定名を参照する運用とし、切替はビューのみ
CREATE OR REPLACE VIEW analytics.dim_customers AS
SELECT * FROM analytics.versioned.dim_customers_v2;

定義と参照の基本：YAMLで宣言、refでバージョン指定

モデル・バージョンはYAMLのプロパティで宣言します。各バージョンごとに説明やテスト、契約を設定できます。参照側はrefで明示的にバージョンを指定してピン留めします。

組織的には、上流の中間層は常に明示的なバージョンをrefし、外部公開名は互換ビューへ委譲する、という二層構成が安全です。

• versionsでvを整数として宣言し、説明・テストをバージョン単位で管理
• refで明示的にバージョンを指定して依存を固定（ピン留め）
• 外部公開やBI接続には安定名の互換ビューを推奨

YAMLとrefの例

# models/sources_and_marts.yml
models:
  - name: dim_customers
    description: 顧客ディメンション（互換ビュー経由で安定名を公開）
    versions:
      - v: 1
        description: 旧版スキーマ（emailはNULL可）
        tests:
          - dbt_utils.unique_combination_of_columns:
              combination_of_columns: [customer_id]
      - v: 2
        description: 新版スキーマ（email NOT NULL、country_code追加）
        tests:
          - dbt_utils.unique_combination_of_columns:
              combination_of_columns: [customer_id]
          - not_null:
              column_name: email

-- models/dim_customers_v2.sql（例）
-- v=2 用の定義。SQL本体は任意の場所に置けますが、命名で区別すると運用しやすい
select ...

-- 下流モデル側の参照例（v=2に明示ピン留め）
select * from {{ ref('dim_customers', v=2) }}

スキーマ契約（contracts）で“壊れない約束”を明文化

バージョン運用の鍵は、壊してはいけない約束を明文化することです。dbtのcontractsをenforcedにすると、カラム順序・型・存在がモデル定義と一致しない場合にビルドを失敗させられます。

破壊的変更を入れる場合は新しいバージョンを宣言し、契約を満たした上で並行稼働させ、消費側の切替が完了したら旧版を廃止します。

• contractsをenforced: trueにして型やNOT NULLなどを厳格化
• 破壊的変更は必ず新バージョン。旧版を急に置換しない
• テスト（unique, not_null）と合わせてCIで自動検証

契約の宣言例（バージョンごとに厳格化）

# models/marts.yml
models:
  - name: dim_customers
    versions:
      - v: 1
        config:
          contract:
            enforced: true
        columns:
          - name: customer_id
            data_type: integer
            tests: [not_null]
          - name: email
            data_type: varchar
      - v: 2
        config:
          contract:
            enforced: true
        columns:
          - name: customer_id
            data_type: integer
            tests: [not_null]
          - name: email
            data_type: varchar
            tests: [not_null]
          - name: country_code
            data_type: varchar

互換レイヤの作り方：安定名を守り、参照先だけを切替

外部に公開する安定名（例: analytics.dim_customers）は、互換レイヤで提供します。SnowflakeやDatabricksではビューを使うのが一般的で、切替時はCREATE OR REPLACE VIEWで参照先をv1からv2に差し替えます。

切替は運用手順に組み込み、権限・メタデータ・依存関係（BIツールのキャッシュなど）の更新もチェックリスト化しておくと安全です。

• 安定名は常にビュー。物理テーブルはバージョン付きで共存
• 切替はトランザクションまたは単一DDLで瞬断を最小化
• 戻し手順（ビューを旧版へ差し戻す）を常備

プラットフォーム別の互換ビュー例

-- Snowflake
CREATE OR REPLACE VIEW analytics.dim_customers AS
SELECT * FROM analytics.versioned.dim_customers_v1;  -- 切替前

-- 切替
CREATE OR REPLACE VIEW analytics.dim_customers AS
SELECT * FROM analytics.versioned.dim_customers_v2;  -- 切替後

-- Databricks (Unity Catalog)
CREATE OR REPLACE VIEW analytics.dim_customers AS
SELECT * FROM analytics_versioned.dim_customers_v2;

安全なリリースとロールバック手順

リリースは「準備→並行→切替→監視→廃止」の順に進めます。v2をビルド・検証した上でまずは互換ビューの消費者を限定して切替え、問題がなければ全体へ拡大します。問題が出たら、互換ビューの参照先を即座にv1へ戻します。

増分モデルやスナップショットを含む場合は、v2の初回ビルド時に完全再計算やバックフィルの計画も合わせて検討します。

• 準備: v2を作成し、contractsとテストをCIで合格
• 並行: v1とv2を同時にビルドし、限定ユーザで検証
• 切替: 互換ビューの参照先をv2へ、監視でエラー・指標の差分確認
• ロールバック: ビューをv1へ戻すだけで即時復旧
• 廃止: 依存がゼロになったらv1を計画的に削除

運用時の代表的なコマンドと手順メモ

# 1) v2モデルのみを事前にビルド・テスト
# （選択子は環境に合わせて指定。例：モデル名やタグでフィルタ）
dbt run  --select dim_customers+  # 依存含めてビルド
dbt test --select dim_customers

# 2) 互換ビューの参照先を切替（即時ロールバック可）
-- CREATE OR REPLACE VIEW analytics.dim_customers AS SELECT * FROM ..._v2;

# 3) 問題があれば即戻す
-- CREATE OR REPLACE VIEW analytics.dim_customers AS SELECT * FROM ..._v1;

試験で狙われる観点と現場の落とし穴

試験では、破壊的変更時の安全な手順やrefのバージョン指定、contractsの役割が定番です。現場では“つい”安定名を直接置換しがちなので、互換ビューを前提にした運用設計が差になります。

また、移行の長期化を避けるため、旧版の廃止計画（期限・影響者連絡・メトリクス監視）を最初から設計に含めておくと良いでしょう。

• refで明示的にバージョンを指定して依存を固定する
• contracts enforcedでスキーマ破壊をCI段階で検知する
• 互換ビューで安定名を提供し、切替とロールバックを迅速化
• 旧版の廃止計画とテレメトリ（利用者・クエリ計測）を準備

“NG/OK”思考の例

# NG: 直接置換で一斉変更
#   CREATE OR REPLACE TABLE analytics.dim_customers AS ...  -- 破壊的変更
# OK: 併存と互換ビュー
#   1) dim_customers_v2 を作成
#   2) 互換ビュー analytics.dim_customers を v2 へ差替
#   3) 監視・問題時はビューを v1 に戻す

問題で確認

よくある質問