背景：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と連携する際にもこの設定の正確性が前提となるため、早い段階で正しい理解と設計パターンを身につけることが、モダンデータスタックを扱う上での大きな武器となるでしょう。