dbt project 構成：フォルダと materialization

Stage 1 — 第3章 | dbt入門カリキュラム 推定学習時間：30〜40分 | 難易度：★★☆☆☆

この章で学ぶこと

dbt プロジェクトは、フォルダ構成 と dbt_project.yml で「どこに何を書くか」をチーム共有します。 一般論として、モデル SQL は models/ 配下、test は tests/ や YAML、静的マスタは seeds/ に置く、という整理がよく使われます。

この章では、その一般構造を押さえたうえで、DS Playground の dsplayground_analytics を開いたときに何が見えるかを読み解きます。

この章を終えると、こんなことができるようになります：

• models/staging / intermediate / marts の 責務の違い を説明できる
• dbt_project.yml の +materialized 既定が各レイヤーにどう効くか読める
• tests/、seeds/、macros/、snapshots/ の 役割 を区別できる
• 次章の source('supabase', ...) が どのフォルダ文化 の上に載るか説明できる

dbt プロジェクトのフォルダ構成、dbt_project.yml のレイヤー設定、materialization の既定値を読み解く章です。

1. プロジェクトの基本情報

dsplayground_analytics の dbt_project.yml 冒頭は次のとおりです。

name: dsplayground_analytics
          version: "1.0.0"
          config-version: 2

          profile: dsplayground_analytics

          model-paths:
            - models
          test-paths:
            - tests
          seed-paths:
            - seeds
          macro-paths:
            - macros
          snapshot-paths:
            - snapshots
          analysis-paths:
            - analyses
          

重要なのは「接続文字列は repo 外」という 境界 です（データマネジメント入門 Stage 5 のガバナンスと同型）。

2. レイヤー別 materialization 既定

同ファイルの models: セクションが、フォルダ名 → マテリアライズ の契約です。

models:
            dsplayground_analytics:
              staging:
                +materialized: view
              intermediate:
                +materialized: view
              marts:
                +materialized: table
          

個別モデルで上書きも可能です（例: 日次集計の incremental mart）。 ただし 既定の 3 段 が、レビュー時の「どこまでが BI 公開物か」の目印になります。

production は analytics スキーマ、CI は analytics_ci スキーマに build します。 フォルダ構成は同じでも、書き込み先スキーマだけ が環境で切り替わります。

3. フォルダツリー

次のツリーは、主要パスを 圧縮した概観 です。 実 repo には target/（build 生成物）や logs/ もありますが、Git 管理の本体 は次のとおりです。

dbt/dsplayground/
          ├── dbt_project.yml          # プロジェクト設定・レイヤー既定
          ├── packages.yml             # 外部 dbt パッケージ（利用時）
          ├── models/
          │   ├── overview.md          # dbt docs 用プロジェクト概要
          │   ├── semantic_ontology.md # 会員・アクティブ等の語彙定義
          │   ├── exposures.yml        # Metabase ダッシュボードとの対応（内部）
          │   ├── staging/
          │   │   └── supabase/
          │   │       ├── _supabase__sources.yml
          │   │       ├── _staging__models.yml
          │   │       ├── stg_supabase__consents.sql
          │   │       ├── stg_supabase__problem_attempts.sql
          │   │       └── ...（他の Supabase 生表）
          │   ├── intermediate/
          │   │   └── product/
          │   │       ├── _intermediate__models.yml
          │   │       ├── int_user_activity_events.sql
          │   │       └── int_member_status_current.sql
          │   └── marts/
          │       ├── product/         # 会員・アクティブ・エンゲージメント
          │       ├── content/         # 練習問題品質
          │       └── surveys/         # アンケート・学習目的
          ├── tests/
          │   ├── _tests.yml           # singular test の説明
          │   └── assert_skill_check_total_score_valid.sql
          ├── seeds/
          │   ├── _seeds.yml
          │   └── practice_problem_catalog.csv
          ├── macros/
          │   └── safe_ratio.sql
          ├── snapshots/
          │   └── snapshot_user_learning_preferences.sql
          └── analyses/                # 探索用 SQL（mart には載せない）
          

命名規則の要点:

4. models 配下のサブドメイン

marts は ビジネス問い ごとにサブフォルダに分かれています。

staging は ソースシステム単位（supabase/）、intermediate は 再利用ロジック単位（product/）です。 データアナリティクス入門のマート設計 で学ぶ「1 表 1 問い」が、フォルダ名レベルでも読み取れます。

5. tests / seeds / macros / snapshots

6. docs と語彙ファイル

models/overview.md と semantic_ontology.md は、dbt docs 生成時に プロジェクトの README 相当 として表示されます。

データマネジメント入門のオントロジー で学ぶ「同じ語を揃える」作業が、analytics 専用の語彙ファイル として repo に存在します。

体系コラム：カリキュラム上の位置づけ

まとめ

この章のキーメッセージ：

dbt プロジェクトは SQL ファイルの袋ではなく、レイヤー・命名・yml・テストがセットの設計図 です。 ツリーを読めると、以降の各章で示す SQL 断片の 居場所 が一気に明確になります。

関連教材

• 前章: なぜ dbt Core か
• 前章: dbt はデータ可視化基盤のどこにいるのか
• 次章: source 定義：外部データとの契約を書く
• 関連: テーブル・ビュー・マテビュー — materialization の背景

確認問題

問題 1

dbt_project.yml で marts に +materialized: table が設定されている主な理由として最も適切なのはどれですか。

A. 本番 OLTP スキーマを table で上書きするため
B. BI ツールが毎回 view チェーンを再計算せず、安定した読み取り先を持つため
C. seed CSV を自動生成するため
D. singular test を marts フォルダにしか置けないため

正解: B

解説: marts を table にすることで、ダッシュボード読み取りを build 時点のスナップショット に寄せ、BI 負荷と定義の安定性を両立します。

問題 2

ファイル stg_app__orders.sql の置き場所として 最も妥当 なのはどれですか。

A. models/marts/sales/
B. models/staging/app/
C. seeds/
D. tests/

正解: B

解説: stg_<source>__<table> は staging / ソース単位 の命名です。mart 化は下流の int_ / fct_ が担います。

問題 3

リポジトリ内 CSV から load する静的マスタは、通常どのディレクトリに置きますか。

A. models/staging/
B. seeds/
C. macros/
D. snapshots/

正解: B

解説: アプリ DB ではなく Git 管理の参照データ は seed です。dbt seed で warehouse に載せます。

用語メモ（この章）