dbtのconfig()関数で行うモデル内設定上書き

dbtでは、同じ設定キーを複数の場所で定義できます。どこで設定すると、どのように上書きされるのかを正しく理解しておくことは、Analytics Engineer試験でも実務でも重要です。

この記事では、config()関数を使ってモデル内で設定を上書きする際の基本、優先順位、インクリメンタルモデルでの注意点、環境別切り替え、YAMLとの棲み分け、そして試験対策の観点を実務寄りに解説します。

config()の基本と上書き優先順位

config()はモデルファイル内のJinjaブロックで設定を記述する仕組みです。代表例として、materialized、schema、alias、tags、インクリメンタル関連のunique_keyやon_schema_changeなどがあります。

同じキーが複数箇所で定義された場合の優先順位は、一般に次の通りです。低: dbt_project.yml → 中: リソースプロパティYAML(モデルの.yml) → 高: モデル内config()。この優先順位を押さえることで、どこで上書きすべきか迷いません。

• config()はJinja評価時に解決されるため、モデルSQLの先頭で宣言しておくのが安全
• 上書きはキー単位。未指定のキーは下位の設定が引き継がれる
• CLIフラグ（例: --full-refresh）は一部の挙動を別途上書きする特例として理解しておく

設定の上書き優先順位（上ほど強い）

最低限のconfig()サンプル

{{ config(
    materialized='table',
    schema='mart',
    alias='orders_daily'
) }}

select * from {{ ref('stg_orders') }}

モデルでよく上書きする設定キー

config()で上書きする頻度が高いのは、materialized、schema、alias、tags、persist_docs（カラム説明の永続化）あたりです。ドキュメント性と運用を意識して選択しましょう。

特にschemaやaliasは命名規約と運用フローに直結します。プロジェクト既定を守りつつ、例外的なモデルのみモデル内で上書きするのが現実的です。

• materialized: view, table, incremental など
• schema/alias: 命名・配置の例外対応に有効
• tags: 選択実行やオーナーシップ管理に便利
• persist_docs: descriptionをカラムコメントへ反映（対応Warehouseのみ）

代表的なconfig()キーの例

{{ config(
    materialized='view',
    schema='sandbox',
    alias='vw_customer_latest',
    tags=['customer', 'sla_daily'],
    persist_docs={'relation': true, 'columns': true}
) }}

select * from {{ ref('stg_customer') }}

インクリメンタルモデルでのconfig()上書き

インクリメンタルでは、materialized='incremental'に加えて、unique_keyや戦略、on_schema_changeなどを適切に設定します。Warehouse固有の戦略オプション（例: merge、insert_overwrite など）はサポート状況に依存します。

unique_keyは行の同一性を定義し、merge戦略では更新対象カラムの制御（例: merge_update_columns）やスキーマ変更時の扱い（on_schema_change）が重要です。試験では、これらのキーの役割と上書き優先順位が頻出です。

• unique_key: 行の一意識別（必須かどうかは戦略とWarehouseに依存）
• incremental_strategy: 代表的にmerge、insert_overwriteなど
• on_schema_change: ignore / append_new_columns / fail など（サポートはWarehouse依存）

インクリメンタル用config()のひな型

{{ config(
    materialized='incremental',
    unique_key='order_id',
    incremental_strategy='merge',
    on_schema_change='append_new_columns'
) }}

with src as (
  select * from {{ ref('stg_orders') }}
)
select * from src

{% if is_incremental() %}
  -- 例: 直近90日分のみ対象
  where order_date >= dateadd(day, -90, current_date)
{% endif %}

環境別にconfig()で切り替える

target.nameやvar()を用いた条件分岐は、開発・検証・本番でスキーマやマテリアライズ方法を切り替える実務で定番です。Jinjaはパース時に評価されるため、条件はモデル先頭のconfig()ブロックで完結させます。

過度な条件分岐は可読性を下げます。プロジェクト既定はdbt_project.ymlで定め、例外のみconfig()で上書きするのが管理しやすいです。

• target.nameで環境ごとのスキーマを制御
• var()で軽微な挙動変更を注入（デフォルト値も用意）
• 条件はconfig()内に閉じると追跡が容易

環境別切り替えの例

{% set is_heavy = var('heavy_model', false) %}
{% if target.name == 'prod' %}
  {{ config(schema='mart', materialized= 'table' if is_heavy else 'view') }}
{% else %}
  {{ config(schema=target.name ~ '_mart', materialized='view') }}
{% endif %}

select * from {{ ref('stg_heavy_fact') }}

YAMLとモデル内config()の棲み分け

変更頻度が低く説明的な設定（例: persist_docs、タグ、オーナー、契約など）はYAMLに寄せると見通しが良くなります。一方で、実行戦略に密接な一時的・例外的な上書きはモデル内config()が扱いやすいです。

試験では「どこに何を書くのが適切か」を問う設問が出ます。プロジェクト既定はdbt_project.yml、モデル固有の静的メタはYAML、環境や戦略の例外はconfig()という三層で整理しておくと回答が安定します。

• 静的メタ・説明はYAML、挙動の例外はconfig()
• 規約はdbt_project.ymlで集約し、逸脱は最小限に
• レビュー時はモデル先頭のconfig()とYAMLをセットで確認

YAMLとconfig()の対比例

# models/schema.yml
models:
  - name: fct_orders
    description: 受注ファクト。
    config:
      tags: ['finance']

-- models/fct_orders.sql
{{ config(materialized='incremental', unique_key='order_id') }}
select * from {{ ref('stg_orders') }}

試験対策と実務ベストプラクティス

Analytics Engineer試験では、設定の優先順位、インクリメンタルの必須キー、on_schema_changeの意味、config()を置く位置などが問われます。特定のWarehouse固有オプションは出題されても一般論で解ける範囲で設問が組まれやすいです。

実務では、プロジェクト既定を強くし、例外はモデル側に閉じ、PRレビューで意図の可視化（なぜ上書きが必要か）をコメントに残す運用が効きます。

• 優先順位: dbt_project.yml < YAML properties < モデル内config()
• インクリメンタル: unique_keyの意味と戦略の相性を説明できること
• config()はモデル先頭のJinjaブロックで宣言し、条件分岐は最小限に

レビューで差がつく最小上書きパターン

{{ config(materialized='incremental', unique_key='id') }}
-- 既定のschema/alias/tagsはdbt_project.yml/YAMLに任せ、
-- ここでは戦略に直結するキーのみ上書き
select * from {{ ref('stg_dim_user') }}

問題で確認

よくある質問