dbtのanalysesディレクトリ徹底活用：一時SQLと再利用の勘所

analysesは、dbtでコンパイルだけを行う分析用SQLの置き場です。モデルのようにdbt runで実行・永続化はされませんが、refやsource、マクロを活用でき、チーム内で共有可能な“一時SQL”をバージョン管理できます。

本稿では、analysesの役割、再利用パターン、運用ベストプラクティス、モデル化への昇格判断、コンパイル挙動までを、Analytics Engineer認定の出題傾向を意識して解説します。詳細仕様はdbt公式ドキュメントを参照してください。

analysesの役割と基本挙動

analyses配下のSQLはdbt compileでJinjaやref/sourceを解決し、target/compiled以下に出力されます。dbt runでは実行されないため、倉庫へのテーブル・ビュー作成は起きません。アドホック分析を再現可能な形で残せるのが利点です。

docs generateでドキュメント化すると、Analysesとしてナビゲーションに現れます。説明文やタグはYAMLで管理可能です。大きな特徴は“実行責務が開発者側にある”ことです。重いクエリを常時運用したい場合はモデル化を検討しましょう。

• 実行対象ではなく“コンパイル対象”。dbt run/ buildには含まれない
• refやsource、macros、var、env_varなどJinjaは利用可
• target/compiled/<project>/analysesに最終SQLが出力される
• ドキュメントサイトにAnalysesとして表示される

analysesの作業フロー

最小のanalysis例: analyses/user_growth.sql

-- analyses/user_growth.sql
-- モデルusers_daily, orders_dailyを参照し、週次成長を確認
with u as (
  select * from {{ ref('users_daily') }}
), o as (
  select * from {{ ref('orders_daily') }}
)
select
  u.ds as week_start,
  count(distinct u.user_id) as weekly_active_users,
  sum(o.order_amount) as weekly_gmv
from u
left join o on o.user_id = u.user_id and o.ds = u.ds
where u.ds >= dateadd('day', -90, current_date)
group by 1
order by 1 desc;

再利用の型: ref/source・マクロ・変数の使いどころ

analysesでは、モデルやソースをref/sourceで参照でき、同じロジックをJinjaマクロ化して呼び出せます。これにより“一時SQL”でも本番ロジックと整合した結果を得られ、検証や探索の再現性が高まります。

変数varや環境変数env_varでパラメータ化しておくと、倉庫や期間の切り替えも容易です。重たい共通ロジックはマクロ化、クエリ構造そのものを共通化したいならエフェメラルモデルの併用も検討します。

• 集計や正規化ロジックはマクロ化してanalyses/モデル双方から利用
• 期間・閾値などはvarで外出し（profilesやdbt_project.yml）
• スモールスタート: まずanalysisで検証→繰り返し使うならモデル化
• インラインCTEが肥大化する場合はエフェメラルモデルで分割

マクロ再利用の例（analysesから呼び出し）

-- macros/metrics.sql
{% macro sum_if_positive(col) %}
    case when {{ col }} > 0 then {{ col }} else 0 end
{% endmacro %}

-- analyses/profit_probe.sql
with f as (
  select * from {{ ref('fact_orders') }} where order_date >= {{ var('start_date', 'current_date - interval 30 day') }}
)
select
  order_date,
  sum({{ sum_if_positive('gross_profit') }}) as profit_pos
from f
group by 1
order by 1 desc;

一時SQL運用ベストプラクティス

ファイル命名は目的が分かるように、期間・粒度などを含めます。例: retention_probe_90d.sql。補足はYAMLで記述し、誰が何のために使うかを明示します。

倉庫で実行する前に常にdbt compileで解決後SQLを確認します。特にrefの解決先や変数展開が期待通りかをチェックします。高コストクエリはLIMITやサンプリングを入れるドラフト版と、本番版を分けるのが無難です。

• 命名規約: 目的_対象_粒度や期間を含める
• analysesごとに説明・タグをYAMLで管理し検索性を上げる
• compile出力をレビューしてから倉庫で実行
• 重い結合・長期期間はまず小範囲で検証（LIMIT、whereで絞る）
• レビュー後にPRで共有、陳腐化したanalysisは定期的に整理

analysesのメタ情報をYAMLで管理（schema: analyses.yml）

version: 2
analyses:
  - name: user_growth
    description: 直近90日の週次ユーザー成長とGMVを可視化する一時分析。モデルusers_daily, orders_dailyに依存。
    tags: ['ad-hoc', 'growth']
  - name: profit_probe
    description: 利益の符号を正規化して直近期間を点検。
    tags: ['ad-hoc', 'finance']

analysisからモデルへ昇格させる判断と移行手順

同じanalysisを繰り返し実行している、ダッシュボードの常設指標として参照したい、他のモデルの下流で再利用したい、といった場合はモデル化を検討します。モデル化によりスケジューリングと依存関係管理、テスト自動化が可能になります。

移行は、analysisのSQLをmodels配下へ移し、テスト・ドキュメントを付与、必要に応じてmaterialization（view/table/incremental）を選びます。エフェメラルにして他モデルへインライン展開する選択肢もあります。

• 判断基準: 実行頻度が高い・他者が継続利用・下流依存がある
• models配下へ移設し、unique/not_nullなどのテストを追加
• スケジュールはdbt Cloudやオーケストレーターで実行
• 重い場合はincrementalや集約テーブル化を検討

移行の最小例

-- 1) analyses/user_growth.sql を models/user_growth.sql へ移動
-- 2) models/user_growth.sql にmaterializationとテストを追加

-- models/user_growth.sql
{{ config(materialized='view') }}
with u as (
  select * from {{ ref('users_daily') }}
), o as (
  select * from {{ ref('orders_daily') }}
)
select u.ds as week_start,
       count(distinct u.user_id) as weekly_active_users,
       sum(o.order_amount) as weekly_gmv
from u left join o on o.user_id = u.user_id and o.ds = u.ds
group by 1

-- tests/schema.yml
version: 2
models:
  - name: user_growth
    tests: []
    columns:
      - name: week_start
        tests: [not_null]
      - name: weekly_active_users
        tests: [not_null]
      - name: weekly_gmv
        tests: [not_null]

コンパイル・ドキュメント生成と挙動の注意点

analysesはdbt compileでのみ有効化され、dbt runやdbt buildでは実行されません。lsで対象を列挙でき、docs generateでドキュメント化されます。refやsourceは解析されますが、実行されないため倉庫側の権限・コストは手動実行時にのみ発生します。

大規模プロジェクトでは、不要なanalysisの放置によりドキュメントが肥大化しやすいため、タグで絞り込みやフォルダ分割を行うとよいでしょう。

• dbt compileはanalysesをtarget/compiledに出力
• dbt run/buildには含まれない（試験での頻出ポイント）
• dbt ls --resource-type analysis で一覧化可能
• docs generateでAnalysesとしてナビゲーションに出現

よく使うコマンド

# 解析のみ（analysesを含む）
dbt compile

# analysesノードの列挙
dbt ls --resource-type analysis

# ドキュメント生成と閲覧
dbt docs generate
dbt docs serve  # ローカル確認用

試験対策の要点と実務チェックリスト

Analytics Engineer試験では、analysesは“コンパイルのみで、dbt runでは実行されない”点、ref/sourceやマクロが使える点、ドキュメントに表示される点が問われやすいです。分析を継続運用したい場合にモデルへ昇格させる、という判断もセットで覚えましょう。

実務では、analysesを“安全な下書き兼ナレッジ共有”と位置づけ、命名・YAMLメタ・レビュー・クリーンアップの運用を定着させると、分析速度と品質の両方が上がります.

• 試験: analysesはcompile対象、run非対象
• 試験: analysesでref/source・マクロ利用可
• 試験: ドキュメントでAnalysesとして表示
• 運用: 命名・メタ情報・レビュー・棚卸しを定期化

実務チェックリスト（抜粋）

- [ ] 命名規約に従い、目的・期間・粒度をファイル名に含めたか
- [ ] YAMLでdescription/tags/ownersを記述したか
- [ ] dbt compile結果をレビューしたか
- [ ] 重いクエリはドラフト版でスコープを絞ったか
- [ ] 繰り返し利用の兆候があればモデル化を検討したか

問題で確認

よくある質問