背景：dbt活用が当たり前になった時代に必要な設定知識
近年、データ分析基盤のモダナイズにおいてdbt（data build tool）は欠かせない存在となっています。特に、SnowflakeやBigQueryなどのDWHと組み合わせたデータ変換処理の自動化に強みがあり、エンジニア1〜3年目でも触れる機会が急増中です。
その中でも、プロジェクトの中核ファイルとなるdbt_project.ymlは設定次第でプロジェクトの成否を左右します。本記事では、models配下にフォルダを作成してdbt runしたときに発生しがちな落とし穴に焦点を当て、エラー回避の実践Tipsまでを一貫して解説します。
dbt_project.ymlの役割と構成要素の基本
dbt_project.ymlは、dbtプロジェクト全体の設定を定義するYAMLファイルで、プロジェクトの「設計図」ともいえる存在です。主に以下の情報が含まれます：
- name：プロジェクト名
- profile：接続先DWHのプロファイル名
- model-paths：モデル（SQLファイル）の格納パス
- models：各モデルのmaterializationやschemaの設定
特にmodelsセクションは、フォルダ構造と密接に関係し、誤解したまま実行すると想定外の出力やエラーの原因になります。
よくある課題・エラーとその背景
実務でよく遭遇する課題やQiita上で注目された事例には、以下のようなものがあります：
- --selectが効かない：フォルダ構成とdbt_project.ymlの記載が一致していない
- 意図しないスキーマや別名のテーブルが作られる：モデル設定の記載漏れや誤設定
- モデルが認識されない：YAMLのインデントミスやパス指定の漏れ
これらのエラーは、すべてmodels配下のフォルダ構成とdbt_project.ymlの記述のズレによって引き起こされます。初心者がつまずく典型的なポイントです。
実践：フォルダ構成とdbt_project.ymlの正しい書き方
以下に、正しいdbt_project.ymlの記載例とディレクトリ構成例を示します。
# ディレクトリ構成
models/
├── sales/
│ └── daily_sales.sql
├── marketing/
│ └── campaign.sql
# dbt_project.yml
name: 'my_project'
version: '1.0.0'
config-version: 2
profile: 'my_project_profile'
model-paths: ["models"]
models:
my_project:
sales:
+schema: sales_schema
+materialized: table
marketing:
+schema: mkt_schema
+materialized: view
このように、models.my_project.salesのようにフォルダ名とファイルパスが一致していないと、dbt run時に対象モデルが見つからないエラーが発生します。特に注意すべきは、プロジェクト名（name）とmodelsセクション直下のキーが一致していることです。
ベストプラクティスと運用Tips
- YAMLのインデントはタブではなくスペースで。構文エラーの元。
- ディレクトリ構成を事前に設計し、modelsセクションと照合しながら記述。
- モデルを追加したら、dbt debugと
dbt lsで対象モデルが認識されているか確認。 - materializationやschema指定は、フォルダ単位で共通設定すると管理が楽。
- 必要に応じて、--select フォルダ名.ファイル名で個別実行テストを行う。
まとめと今後の展望
dbtプロジェクトにおけるdbt_project.ymlの設定は、プロジェクトの実行性・保守性を大きく左右する重要な構成要素です。特にmodelsディレクトリ配下の構成を正しく管理することで、エラーを未然に防ぎ、チーム開発や本番運用への移行もスムーズに行えます。
今後、CI/CDやAirflowと連携する際にもこの設定の正確性が前提となるため、早い段階で正しい理解と設計パターンを身につけることが、モダンデータスタックを扱う上での大きな武器となるでしょう。