answering-natural-language-questions-with-dbt

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	セマンティックレイヤーは有効だが、軽微な変更が必要（ディメンションの欠落、カスタムフィルター、case when、異なる集計）	コンパイル済み SQL を変更する	get_metrics_compiled_sql の後に execute_sql
3	セマンティックレイヤーがなく、探索ツールが有効	モデルを調査して 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 ではなく、生の SQL が返されます）
2. 必要なものを追加するよう SQL を変更する
3. execute_sql で生の SQL を実行する
4. 変更を再利用できる場合は、必ずセマンティックモデルの更新を提案する

-- Example: Adding sales_rep dimension
WITH base AS (
    -- ... compiled metric logic (already resolved to table names) ...
)
SELECT base.*, reps.sales_rep_name
FROM base
JOIN analytics.dim_sales_reps reps ON base.rep_id = reps.id
GROUP BY ...

-- Example: Custom filter
SELECT * FROM (compiled_metric_sql) WHERE region = 'EMEA'

-- Example: Case when categorization
SELECT
    CASE WHEN amount > 1000 THEN 'large' ELSE 'small' END as deal_size,
    SUM(amount)
FROM (compiled_metric_sql)
GROUP BY 1

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

アプローチ 3：モデルの探索

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

1. get_mart_models - ステージングではなく、まずマートから確認する
2. 関連するモデルについて get_model_details を実行し、スキーマを把握する
3. {{ ref('model_name') }} を使用して SQL を作成する
4. show --inline "..." または execute_sql

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

アプローチ 4：マニフェスト／カタログの分析

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

1. target/manifest.json と target/catalog.json があるか確認する
2. 読み取る前に絞り込む - これらのファイルは大きい場合があります

# Find mart models in manifest
jq '.nodes | to_entries | map(select(.key | startswith("model.") and contains("mart"))) | .[].value | {name: .name, schema: .schema, columns: .columns}' target/manifest.json

# Get column info from catalog
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 全体を読む
• マートモデルがあるのにステージングモデルを使う
• ビジネス上の質問への回答ではなく、モデルの正しさの検証に使う

よくある間違い

間違い	対処法
SL で直接回答できないと諦める	コンパイル済み SQL を取得して変更します
ステージングモデルにクエリを実行する	まず get_mart_models を使います
manifest.json 全体を読む	jq でフィルタリングします
ETL の変更を提案する	提案はセマンティックレイヤーの範囲内にとどめます
ツールが利用可能か確認しない	アプローチを選ぶ前に、利用可能なツールを一覧表示します