dbt を使った自然言語質問への回答

概要

データ質問に最適な方法で回答します：セマンティックレイヤー優先、次に SQL 修正、モデル発見、マニフェスト分析の順です。回答できないと言う前に、すべてのオプションを試し尽くしてください。

用途： ユーザーからのデータ回答が必要なビジネス質問

• 「先月の総売上はいくら？」
• 「アクティブな顧客数は？」
• 「地域別の収益を表示してほしい」

用途外：

• 開発中のモデルロジックの検証
• dbt モデルまたはセマンティックレイヤー定義のテスト
• dbt モデルの構築または修正
• dbt run、dbt test、dbt build ワークフロー

意思決定フロー

flowchart TD
    start([Business question received])
    check_sl{Semantic layer tools available?}
    list_metrics[list_metrics]
    metric_exists{Relevant metric exists?}
    get_dims[get_dimensions]
    sl_sufficient{SL can answer directly?}
    query_metrics[query_metrics]
    answer([Return answer])
    try_compiled[get_metrics_compiled_sql<br/>Modify SQL, execute_sql]
    check_discovery{Model discovery tools available?}
    try_discovery[get_mart_models<br/>get_model_details<br/>Write SQL, execute]
    check_manifest{In dbt project?}
    try_manifest[Analyze manifest/catalog<br/>Write SQL]
    cannot([Cannot answer])
    suggest{In dbt project?}
    improvements[Suggest semantic layer changes]
    done([Done])

    start --> check_sl
    check_sl -->|yes| list_metrics
    check_sl -->|no| check_discovery
    list_metrics --> metric_exists
    metric_exists -->|yes| get_dims
    metric_exists -->|no| check_discovery
    get_dims --> sl_sufficient
    sl_sufficient -->|yes| query_metrics
    sl_sufficient -->|no| try_compiled
    query_metrics --> answer
    try_compiled -->|success| answer
    try_compiled -->|fail| check_discovery
    check_discovery -->|yes| try_discovery
    check_discovery -->|no| check_manifest
    try_discovery -->|success| answer
    try_discovery -->|fail| check_manifest
    check_manifest -->|yes| try_manifest
    check_manifest -->|no| cannot
    try_manifest -->|SQL ready| answer
    answer --> suggest
    cannot --> done
    suggest -->|yes| improvements
    suggest -->|no| done
    improvements --> done

クイックリファレンス

優先度	条件	アプローチ	ツール
1	セマンティックレイヤーが有効	メトリクスを直接クエリ	list_metrics、get_dimensions、query_metrics
2	SL 有効だが軽微な修正が必要（ディメンション欠落、カスタムフィルター、CASE WHEN、異なる集計）	コンパイル済み SQL を修正	get_metrics_compiled_sql、その後 execute_sql
3	SL なし、発見ツール有効	モデルを探索、SQL を記述	get_mart_models、get_model_details、その後 show/execute_sql
4	MCP なし、dbt プロジェクト内	アーティファクト分析、SQL 記述	target/manifest.json、target/catalog.json を読み込み

アプローチ 1：セマンティックレイヤークエリ

list_metrics と query_metrics が利用可能な場合：

1. list_metrics - 関連メトリクスを検索
2. get_dimensions - 必要なディメンションが存在することを確認
3. query_metrics - 適切なフィルターを使用して実行

セマンティックレイヤーが直接回答できない場合（ディメンション欠落、カスタムロジックが必要）→ アプローチ 2 へ進みます。

アプローチ 2：修正されたコンパイル済み SQL

セマンティックレイヤーにメトリクスはあるが、軽微な修正が必要な場合：

• ディメンション欠落（結合 + GROUP BY）
• ディメンションとして利用できないカスタムフィルター
• カスタム分類用の CASE WHEN ロジック
• 定義されたものと異なる集計

1. get_metrics_compiled_sql - 実行する SQL を取得（Jinja ではなく raw SQL を返す）
2. SQL を修正して必要な内容を追加
3. execute_sql で raw SQL を実行
4. 常に提案する 修正内容が再利用可能な場合はセマンティックモデルを更新するように

-- 例：sales_rep ディメンション追加
WITH base AS (
    -- ... コンパイル済みメトリクスロジック（既にテーブル名に解決済み） ...
)
SELECT base.*, reps.sales_rep_name
FROM base
JOIN analytics.dim_sales_reps reps ON base.rep_id = reps.id
GROUP BY ...

-- 例：カスタムフィルター
SELECT * FROM (compiled_metric_sql) WHERE region = 'EMEA'

-- 例：CASE WHEN 分類
SELECT
    CASE WHEN amount > 1000 THEN 'large' ELSE 'small' END as deal_size,
    SUM(amount)
FROM (compiled_metric_sql)
GROUP BY 1

注意： コンパイル済み SQL には {{ ref() }} ではなく解決済みテーブル名が含まれます。返された raw SQL のまま作業してください。

アプローチ 3：モデル発見

セマンティックレイヤーはないが get_all_models/get_model_details が利用可能な場合：

1. get_mart_models - ステージング モデルではなく mart から開始
2. 関連モデルの get_model_details - スキーマを理解
3. {{ ref('model_name') }} を使用して SQL を記述
4. show --inline "..." または execute_sql

mart をステージング より優先 - mart にはビジネスロジックが適用されています。

マニフェスト/カタログ分析

dbt プロジェクト内にいるが MCP サーバーがない場合：

1. target/manifest.json と target/catalog.json の存在を確認
2. 読み込み前にフィルタリング - これらのファイルは大きくなる場合があります

# マニフェスト内の mart モデルを検索
jq '.nodes | to_entries | map(select(.key | startswith("model.") and contains("mart"))) | .[].value | {name: .name, schema: .schema, columns: .columns}' target/manifest.json

# カタログから列情報を取得
jq '.nodes["model.project_name.model_name"].columns' target/catalog.json

3. 発見されたスキーマに基づいて SQL を記述
4. 説明：「この SQL はあなたのウェアハウスで実行すべきです。データベースへのアクセスがないため、私は実行することができません。」

改善の提案

dbt プロジェクト内にいる場合、回答後（または回答できない場合）にセマンティックレイヤーの変更を提案します：

ギャップ	提案
メトリクスが存在しない	「セマンティックモデルにメトリクス定義を追加してください」
ディメンション欠落	「セマンティックモデルのディメンションリストに dimension_name を追加してください」
セマンティックレイヤーなし	「このデータにセマンティックレイヤーの追加を検討してください」

セマンティックレイヤーレベルにとどまる。 以下は提案しないでください：

• データベーススキーマ変更
• ETL パイプライン修正
• 「データエンジニアリングチームに聞いてください...」

抵抗すべき正当化

あなたの考え...	現実
「セマンティックレイヤーはこの正確なクエリをサポートしていない」	コンパイル済み SQL を取得して修正してください（アプローチ 2）
「MCP ツールがない、助けられない」	マニフェスト/カタログをローカルで確認してください
「ユーザーはこれを急いでいるので、体系的なチェックをスキップしよう」	体系的なアプローチが最速の道です
「SQL を書く方が速い」	セマンティックレイヤーは理由があって存在します - 最初に使用してください
「ディメンションがデータに存在しない」	もしかしたらセマンティックレイヤー設定には存在しないが、データには存在するかもしれません

赤旗 - 停止

• セマンティックレイヤーが回答できるかチェックしないで SQL を記述
• 4 つのアプローチをすべて試さないで「回答できません」と言う
• セマンティックレイヤーギャップに対してデータベースレベルの修正を提案
• フィルタリングなしで全体の manifest.json を読み込み
• mart モデルが存在するときにステージング モデルを使用
• ビジネス質問に回答するのではなくモデルの正確性を検証するために使用

よくある間違い

間違い	修正
SL が直接回答できないときに諦める	コンパイル済み SQL を取得して修正する
ステージング モデルをクエリ	最初に get_mart_models を使用
全体の manifest.json を読み込み	jq でフィルタリングして使用
ETL 変更を提案	セマンティックレイヤーレベルの提案に留める
ツール利用可能性をチェックしない	アプローチを選択する前に利用可能なツールをリストアップ