dbtのconstraints機能で押さえるべきNOT NULL / PRIMARY KEY実務と試験対策

dbtはモデル作成時にデータウェアハウスの制約（NOT NULL、PRIMARY KEY、UNIQUE、CHECKなど）を付与できるアダプタがあります。これにより、実行時に不正データの書き込みをブロックできます。

一方で、dbtのテスト（generic tests）やモデルコントラクト（contracts）との役割分担を誤ると、意図せず本番ジョブが落ちたり、逆に品質保証が弱くなったりします。本稿は、制約の宣言方法、アダプタ差、移行運用、試験対策の観点で実務に落ちる線を解説します。

制約とテストの役割分担をまず整理する

dbtのconstraints機能は、アダプタ（SnowflakeやDatabricksなど）が対応している場合に、CREATE/ALTER TABLE時にデータベース制約を作成します。これにより、ロード時（INSERT/MERGE）に不正データを書き込めなくなります。

dbtのテストは、ロード後に集計・走査して品質を検証します。制約は“予防”、テストは“検知”の役割です。モデルコントラクト（contracts.enforced）はスキーマの整合（列名・型）を強制する仕組みで、値制約とは別物です。

• 制約: ウェアハウスが実行時に拒否（NOT NULL、CHECK、アダプタによりPRIMARY/UNIQUEの扱いは差異）
• テスト: dbtが後段で検知（not_null、unique、relationshipsなど）
• モデルコントラクト: 列名・型の逸脱をビルド時に拒否（値の妥当性は別途）

dbtにおける制約・テスト・コントラクトの流れ

NOT NULL / PRIMARY KEYなどの宣言方法（dbt側）

アダプタが対応している場合、モデルのconfigやschema.ymlで制約を宣言できます。宣言はDDL生成時に反映されます。既存テーブルに対する追加はアダプタの挙動に依存し、ALTER TABLEで付与される場合と、再作成（--full-refresh）が必要な場合があります。

PRIMARY KEYやUNIQUEの実効性はウェアハウスごとに異なります。たとえばSnowflakeではNOT NULLは強制されますが、PRIMARY KEY/UNIQUEは情報的（enforcedされない）であることがあります。Databricks（Delta Lake）はNOT NULLやCHECKを強制できますが、PRIMARY KEYはネイティブサポートが限定的です。

• 列レベルのNOT NULLは、実行時のバリデーションとして強力
• PRIMARY KEYは、実体としては“unique + not null”の意図表明。Snowflakeでは多くのケースで情報的
• UNIQUEはアダプタの実装に従う（Snowflakeでは情報的、DeltaはCHECKで代替することも）

宣言例（モデルconfigとschema.yml）

-- models/customers.sql
{{ config(
  materialized='table',
  constraints=[
    { 'type': 'primary_key', 'columns': ['customer_id'] },
    { 'type': 'not_null',    'columns': ['customer_id', 'email'] },
    { 'type': 'unique',      'columns': ['email'] }
  ],
  contracts={'enforced': true}
) }}
select
  customer_id::number as customer_id,
  email::string       as email,
  created_at::timestamp as created_at
from {{ ref('stg_customers') }};

# schema.yml（補助的にテストも併用）
models:
  - name: customers
    columns:
      - name: customer_id
        tests:
          - not_null
          - unique
        constraints:
          - type: not_null
          - type: primary_key
      - name: email
        tests:
          - not_null
        constraints:
          - type: not_null

アダプタ別サポート差分（Snowflake / Databricks）

Snowflake: NOT NULLはエンジンで強制されます。PRIMARY KEYやUNIQUEは情報的で、クエリ最適化や実行時の重複拒否を必ずしも保証しません。そのため、実運用ではNOT NULL制約とdbtのuniqueテスト、もしくはモデル側の重複排除ロジックを併用します。

Databricks（Delta Lake）: NOT NULLとCHECK制約を強制できます。PRIMARY KEYは限定的で、ユニーク性の保証はモデルでの去重やマージキーの一意性担保で実現するのが一般的です。

• Snowflake: NOT NULLは強制。PK/UNIQUEは情報的であるケースに留意
• Databricks Delta: NOT NULL/CHECKが有効。PKは限定的
• いずれも、dbtのgeneric testsは併用する（早期検知と可観測性）

Delta LakeでのCHECK代替例（疑似ユニーク制約）

-- Databricks Deltaの例：メールの形式や範囲チェック
{{ config(
  materialized='table',
  constraints=[
    { 'type': 'not_null', 'columns': ['customer_id', 'email'] },
    { 'type': 'check',    'expression': "email LIKE '%@%._%'" }
  ]
) }}
select * from {{ ref('stg_customers') }};

インクリメンタルモデルと制約の相性

インクリメンタルモデルではunique_keyを用いたMERGEを行うケースが多く、NOT NULL制約はそのカラムに対する安全装置になります。制約の追加・変更は、アダプタによってはテーブル再作成が必要となるため、--full-refreshの計画的な実行が求められます。

制約はテーブル作成時に付与されるのが基本です。運用中のテーブルにALTERで追加できるか、dbtが自動でALTERを発行するかはアダプタ実装依存です。変更管理では、ステージング環境で先に制約を試し、本番は低リスクのNOT NULLから段階導入するのが無難です。

• unique_keyは重複を“更新ロジックで”さばく。PK/UNIQUE制約の実効性はアダプタ差
• --full-refreshで制約定義を確実に反映（ダウンタイム計画も）
• on_schema_changeの設定と合わせて、列追加・同期の方針を明確化

インクリメンタルモデルでの設定例

{{ config(
  materialized='incremental',
  unique_key='customer_id',
  on_schema_change='sync_all_columns',
  constraints=[ { 'type': 'not_null', 'columns': ['customer_id'] } ]
) }}

with src as (
  select * from {{ ref('stg_customers') }}
)
select * from src
{% if is_incremental() %}
  -- 追加ロジック（例：更新日時で絞り込み）
  where updated_at > (select coalesce(max(updated_at), '1970-01-01') from {{ this }})
{% endif %}

移行・運用のベストプラクティス

既存テーブルにNOT NULLを追加する場合は、事前にNULL埋めや補正を完了し、dbtのnot_nullテストでグリーンを確認した上で制約を付与します。本番ではまずステージングで適用→本番は低トラフィック時間帯に--full-refresh、が安全です。

PRIMARY KEYやUNIQUEの“意図表明”は有用ですが、Snowflakeのように実効性が限定的な環境では、モデル側での去重（window関数・QUALIFYなど）とテストの併用で一意性を保証します。

• 低リスク順（テスト→NOT NULL→CHECK→PK/UNIQUEの宣言）で段階導入
• dbt Cloud/CIでテストを必須化し、制約追加前後の差分を可視化
• 失敗時リカバリ手順（制約のDROP/再ビルド）を事前に用意

去重の例（一意行のみ残す）

with base as (
  select *,
         row_number() over (partition by customer_id order by updated_at desc) as rn
  from {{ ref('stg_customers') }}
)
select * from base where rn = 1

Analytics Engineer試験で問われやすいポイント

制約・テスト・コントラクトの役割分担を言語化できることが重要です。特にSnowflakeのPK/UNIQUEが情報的である点、NOT NULLは強制される点、DeltaはNOT NULL/CHECKが強い点など、アダプタ差分は頻出です。

“ユニーク性を保証したい＝PK制約で完璧”とは限らない、という落とし穴に注意。現実装ではモデルの去重ロジック＋テストの併用が最も再現性が高いケースが多いです。

• 制約は予防、テストは検知、コントラクトはスキーマ整合の強制
• Snowflake: NOT NULLは強制、PK/UNIQUEは情報的
• Databricks Delta: NOT NULL/CHECKが強力、PKは限定的。ユニーク性はモデルとテストで担保

問題で確認

よくある質問