dbt 命名規則: 一貫性のあるモデル名設計

dbt ではファイル名がそのままモデル名になり、ref・source・セレクタ・ドキュメントの全てで露出します。つまり命名は開発速度と運用品質に直結します。

本稿は dbt 公式の一般的なベストプラクティスに沿い、stg/int/dim/fct などのレイヤを軸に、実務で迷わない命名レシピと試験で問われやすい観点をまとめます。

命名規則の基本方針

dbt のモデル名は小文字スネークケースを基本にし、レイヤを示す短いプレフィックスで始めます。粒度（granularity）が想像できる具体名にし、略語はチームで合意した最小限に抑えます。

特に Analytics Engineer 試験では、stg_{source}_{table} と dim_/fct_ の役割差、セレクタでの絞り込み容易性が問われがちです。

• 小文字_snake_case（半角英数とアンダースコアのみ）
• レイヤは接頭辞で表現: stg_, int_, dim_, fct_, rpt_
• 単数・複数は粒度基準で統一（dim_customer、fct_orders など）
• 外部システム名は短く正規化（salesforce→sf、google_analytics→ga）
• 禁止: 日付や環境を名前に埋め込む、意味のない略語、キャメルケース、スペース

良い/悪い命名の例

# Good
stg_sf_account.sql
int_customer_unified.sql
dim_customer.sql
fct_order_line.sql
rpt_sales_summary.sql

# Bad
StageSalesforceAccount.sql      -- uppercase / camel
staging_accounts.sql            -- layer name too long / inconsistent
customer_v2_new_new.sql         -- meaningless version suffixes
ordersFact.sql                  -- camel + inconsistent prefix

レイヤ別命名と依存の見える化

レイヤごとに役割と粒度を固定し、プレフィックスで一目で分かるようにします。stg はソーステーブルと1対1、int は結合や前処理の中間、dim/fct はマート層の配布用という棲み分けが基本です。

プレフィックスはセレクタでの運用に効きます。例えば dbt build -s stg_* や +fct_* など、命名がそのまま対象選択の表現力になります。

• stg は列名正規化・型変換・軽微なフィルタのみ
• int は複数 stg の結合・重複排除・粒度調整
• dim はディメンションのユニークキーと属性管理、fct はイベント/取引の事実表
• rpt は最終配布用の集計（必要時のみ）

モデル依存関係とフォルダの対応

models/
  staging/
    sf/
      stg_sf_account.sql
      stg_sf_contact.sql
  intermediate/
    int_customer_unified.sql
  marts/
    core/
      dim_customer.sql
      fct_order_line.sql
    reporting/
      rpt_sales_daily.sql

Flow:
source('sf','account') --> stg_sf_account --> int_customer_unified --> dim_customer
                                                        \
                                                         --> fct_order_line --> rpt_sales_daily

セレクタ例（CLI で活きる命名）

# stg だけをビルド
 dbt build -s stg_*

# fct とその上流をすべて（+ は上流/下流依存）
 dbt build -s +fct_*

# 顧客関連だけ（命名の共通部分で束ねる）
 dbt build -s dim_customer int_customer_* stg_*_customer*

フォルダ構成と YAML 定義の整合

フォルダはレイヤとドメインで二段に切ると、スコープごとの schema.yml を置きやすくなります。YAML 上の name はファイル名（=モデル名）と一致させ、description は BI 利用者向けに簡潔に。

プロジェクトの quoting 設定はデフォルト（未指定＝多くのアダプタで非引用）を前提にし、モデル名は小文字で統一します。倉庫によっては実体名が大文字化されますが、論理名（dbt 上の model name）は変わりません。

• schema.yml は models/staging/sf/schema.yml のように近接配置
• 同一ディレクトリのモデルを同一 YAML にまとめるとメンテ容易
• description と tests は命名と粒度を裏切らない内容にする

例: dbt_project.yml と schema.yml

# dbt_project.yml（抜粋）
name: my_dbt
models:
  my_dbt:
    staging:
      +materialized: view
    intermediate:
      +materialized: table
    marts:
      core:
        +materialized: table

# models/staging/sf/schema.yml（抜粋）
version: 2
models:
  - name: stg_sf_account
    description: "Salesforce Account の正規化ビュー（1行=アカウント）"
    columns:
      - name: account_id
        tests: [not_null, unique]
      - name: account_name
        tests: [not_null]
  - name: stg_sf_contact
    description: "Salesforce Contact の正規化ビュー（1行=人物）"
    columns:
      - name: contact_id
        tests: [not_null, unique]

ソース・シード・スナップショットの命名

source は組織内で安定した system 名を与え、テーブル側は実体名に合わせます。stg の命名に source 名を入れてトレースできるようにします。

seed は配布用であれば素直なビジネス名、補助マッピングであれば map_ 前置きなどの一貫した流儀を使います。スナップショットは論理名＝ snapshot ブロック名で、対象テーブルが推測できる明確な名前にします。

• source 名は短く一貫（sf、erp、ga など）
• stg_{source}_{table} で 1:1 を担保
• seed は map_country_codes のように用途が読める名前
• snapshot は対象とキーを連想できる名（snap_customer_scd2 など）

source・seed・snapshot の定義例

# models/staging/sf/sources.yml（抜粋）
version: 2
sources:
  - name: sf
    schema: raw_salesforce
    tables:
      - name: account
      - name: contact

# seeds/proj/map_country_codes.csv -> map_country_codes テーブルに
# dbt_project.yml（抜粋）
seeds:
  +schema: reference
  proj:
    +quote_columns: false

# snapshots/snap_customer_scd2.sql（抜粋）
{% snapshot snap_customer_scd2 %}
  {{ config(
      target_schema='history',
      unique_key='customer_id',
      strategy='check',
      check_cols=['email','status']
  ) }}
  select * from {{ ref('dim_customer') }}
{% endsnapshot %}

テスト・マクロ・エクスポージャの命名

汎用テスト（unique, not_null 等）は YAML で宣言すれば dbt が一貫したテスト名を生成します。独自ロジックは singular テスト（tests ディレクトリの SQL）にし、test_{対象}_{規則} のように名付けます。

マクロは用途を接頭辞で分け、型変換やクリーニング系は util_、ビジネスルールは biz_ など役割が分かる名にします。exposure は BI ダッシュボード単位で exposure_{領域}_{名称} とし、depends_on のモデル名と整合を取ります。

• singular テスト: tests/test_dim_customer_scd.sql など
• マクロ: macros/util_clean_email.sql など
• exposure 名はダッシュボードの永続 ID に合わせると追跡が容易

テストとマクロの例

# models/marts/core/schema.yml（抜粋）
version: 2
models:
  - name: dim_customer
    tests:
      - dbt_utils.unique_combination_of_columns:
          combination_of_columns: [customer_id]
    columns:
      - name: email
        tests: [not_null]

# tests/test_dim_customer_email_format.sql（singular）
select email from {{ ref('dim_customer') }}
where email !~ '^[^@]+@[^@]+\.[^@]+

      

        
        NicheeLab を読み込み中…
      
    
  #x27;

# macros/util_clean_email.sql
{% macro util_clean_email(col) %}
    lower(trim({{ col }}))
{% endmacro %}

# models/staging/sf/stg_sf_contact.sql（利用例）
select
  contact_id,
  {{ util_clean_email('email') }} as email
from {{ source('sf','contact') }}

アンチパターンと例外的なエイリアス運用

アンチパターンは、意味のないバージョン接尾辞、抽象的すぎる名前、レイヤ不一致（例: stg で重結合）です。命名で粒度と責務を裏切るとドキュメントと現物が乖離します。

レガシー互換のために倉庫側のテーブル名を合わせる必要があるときだけ alias を使います。論理名（ファイル名）は規約通り、物理名だけ alias で置き換えると影響を局所化できます。

• 禁止: customer_final_v3_final.sql のような履歴を名前に埋める
• 禁止: marts に stg_ を置く、stg で集計する
• alias は限定的に。常用はしない

alias と引用設定の例

# models/marts/core/dim_customer.sql
{{ config(alias='DIM_CUSTOMER_LEGACY') }}
select * from {{ ref('int_customer_unified') }}

# dbt_project.yml（抜粋: Snowflake 等で大文字化を避けたい場合）
quoting:
  database: false
  schema: false
  identifier: true   # 物理名を引用して大文字化を防ぐ

# 注: 倉庫やアダプタのデフォルト挙動に依存するため、チームで合意の上で設定する

問題で確認

よくある質問