dbt Semantic Layerの使い方 — Claudeでメトリクスに自然言語で問い合わせる

MCPはAIエージェントと外部ツールをつなぐ標準プロトコルで、仕組み自体はMCPとはにまとめています。dbt Semantic Layerは、revenueのような業務指標(メトリクス)の定義をBIツールごとにバラバラに書く代わり、dbtのモデル層に一元化する仕組みです。dbt MCPサーバーにはこのSemantic Layerを操作する7つの専用ツールが含まれており、Claudeに接続すればSQLを書かずに「先月の地域別売上を見せて」のような自然文でメトリクスを問い合わせられます。dbtのモデルをbuild・compile・runで実行したりリネージを追ったりする使い方はdbt MCPサーバーの使い方で扱っており、この記事はSemantic Layer側のツールに絞って手順をまとめます。

dbt Semantic Layerとは — メトリクスをモデル層で一元定義する

dbt Semantic LayerはMetricFlowが動作の中核で、メトリクスの定義をBIレイヤーではなくdbtプロジェクト側に置きます。ある指標の定義が変われば、それを参照しているダッシュボードやレポートすべてに反映されるため、部署ごとに微妙に違う「売上」の定義がバラバラに存在する事態を防げます。

利用にはdbt platformのStarterまたはEnterprise-tierアカウントが必要です。dbt Core単体のプロジェクトではSemantic Layerの照会はできず、メトリクス自体はdbtプロジェクト内で定義しますが、それを外部から問い合わせる経路(APIやMCP)はdbt platform経由に限られます。

使える7つのツール

dbt MCPサーバーのSemantic Layerカテゴリーには次の7ツールがあります。

query_metricsが実際にデータを引く中心のツールで、残りはメトリクスの構造を把握するための補助ツールという位置づけです。メトリクス数が10件以下のプロジェクトでは、list_metricsの応答にディメンションとエンティティの名前が最初から埋め込まれるため(DBT_MCP_SL_METRICS_RELATED_MAXの既定値10)、get_dimensionsを別途呼ばずに済みます。10件を超えるプロジェクトでは、Claudeがメトリクス名を見てから必要な分だけget_dimensions・get_entitiesを追加で呼ぶ2段階の動きになります。

Claudeへの接続方法 — self-hostedとremote

Semantic Layerツールは、dbt MCPサーバーのself-hosted構成とremote構成のどちらからでも使えます。

self-hostedでSemantic Layerも使う場合、claude mcp addにDBT_HOST・DBT_TOKEN・DBT_PROD_ENV_IDの3つを渡します。

claude mcp add dbt \
  -e DBT_HOST=abc123.us1.dbt.com \
  -e DBT_TOKEN=your-token-here \
  -e DBT_PROD_ENV_ID=12345 \
  -- uvx dbt-mcp

DBT_HOSTはアカウント設定のAccess URLのホスト名部分、DBT_PROD_ENV_IDは数値の環境IDで、ブラウザからコピーしたURLそのものではありません。CLIコマンドを使わずSemantic Layerだけに絞りたい場合、DBT_PROJECT_DIRとDBT_PATHを渡さなければCLIツールは自動的に無効化され、dbt platform系のツールだけが有効になります。

Claude Codeからremote MCPサーバーにOAuthで直接つなぐ場合は、.mcp.jsonに次のように書きます。

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}

初回接続時にブラウザが開いてdbt platformへのサインインとスコープの同意を求められます。remote MCP OAuthはStarter・Enterprise・Enterprise+アカウントの公開ベータです。

自然言語でメトリクスに問い合わせる実例

接続が終われば、あとは自然文で聞くだけです。

定義済みのメトリクスを一覧で見せて

list_metricsが呼ばれ、メトリクス数が少なければディメンションとエンティティの名前も一緒に返ってきます。特定の指標を掘り下げたいときは、フィルタとグルーピングを含めて聞きます。

先月のrevenueを地域別・プラン別に見せて

この聞き方ではquery_metricsがrevenueメトリクスにregionとplanのディメンションを指定して呼ばれ、集計済みの結果が返ります。実際にクエリを投げる前にSQLだけ確認したい場合は、聞き方を変えます。

revenueメトリクスをregion別に集計するSQLだけ見せて(実行はしないで)

get_metrics_compiled_sqlはメトリクスをクエリせずコンパイル後のSQLだけを返すため、意図しないウェアハウス実行コストをかけずに定義の妥当性を確認できます。

ディメンションにどんな値が入っているか分からないまま絞り込みたいときは、値の候補を先に確認する聞き方もできます。

revenueメトリクスのregionディメンションには、どんな値が入ってる?

get_dimension_valuesがメトリクスを指定した状態で呼ばれ、実際にそのメトリクスの計算に使われているregionの値だけが返ります。ディメンションのカラム名や表記ゆれ(japanかJPか)を覚えていなくても、値の一覧を見てから絞り込みの条件を組み立てられます。

制限事項を先に確認する

Semantic Layerに接続する前に押さえておく制約が2つあります。1つはレート制限です。remote MCPはdbt platformの他のAPIと同じグローバルレート制限(1IPあたり毎分5,000リクエスト)を共有し、self-hostedはDiscovery APIやAdmin APIの公開レート制限に従います。ダッシュボード的に高頻度でクエリを投げ続ける使い方には向いていません。もう1つはデータ保持です。dbt MCPサーバー自体は本番データやジョブ実行結果を一切保持しない読み取り専用のアクセス層で、ツール呼び出しのたびにdbt platformからリアルタイムで読み出します。ジョブの実行結果がどれだけの期間残るかは、MCPサーバーではなくdbt platform側のデータ保持ポリシーが決めます。

BIダッシュボードとの役割分担

Semantic Layerのメトリクス定義自体はBIツール側の機能を代替するものではなく、BIツールが参照する「メトリクスの定義元」を一本化するものです。dbt Semantic LayerはTableauやLooker、Google Sheetsなど複数の下流ツールと統合できる設計になっており、それらのツールから見えるメトリクスの数値は常に同じdbtの定義に基づきます。Claudeからの自然言語問い合わせは、ダッシュボードを新しく作るまでもない一回限りの確認や、ディメンションを変えながら試行錯誤する探索的な分析に向いています。定期的に配信するレポートや複数人が繰り返し参照するダッシュボードは、引き続きBIツール側で構築し、その裏側の定義だけをSemantic Layerに寄せる使い方が実態に近い役割分担です。ウェアハウス自体に自然言語で直接クエリを投げたい場合は、Claude Snowflake連携のようなDB専用のMCPサーバーという選択肢もあります。Semantic Layerがメトリクス定義を経由するのに対し、こちらは生のテーブルに対する自由なSQL探索に向いています。

よくあるつまずき

• list_metricsが空を返す: dbt platformアカウントがStarter/Enterprise-tierでない、またはプロジェクトにメトリクスが定義されていない。プロジェクト側でsemantic_modelsとmetricsが定義済みか確認する
• DBT_PROD_ENV_IDにURLをそのまま貼ってしまう: DBT_PROD_ENV_ID・DBT_DEV_ENV_ID・DBT_USER_IDはいずれも数値IDが必要で、ブラウザからコピーしたURLをそのまま渡すと接続に失敗する
• query_metricsの応答が途中で削られる: list_metricsのCSV応答は既定で16,000文字を超えるとdescriptionとmetadata列が省略される(DBT_MCP_SL_MAX_RESPONSE_CHARS)。全文が必要な場合は同変数を大きくするか0にして省略を無効化する
• サービストークンでexecute_sqlが動かない: execute_sqlはPATでのみ動作する仕様で、サービストークンでは失敗する。SQL実行も使いたい場合はPATに切り替える

よくある質問

dbt Core単体のプロジェクトでも使えますか

Semantic Layerの照会自体はdbt platformのStarter/Enterprise-tierアカウントが前提のため、dbt Core単体では使えません。メトリクスの定義はdbt Core上のプロジェクトファイルに書けますが、それをMCP経由でクエリするにはdbt platform側の環境IDとトークンが必要です。

保存済みクエリ(saved queries)とは何ですか

dbtプロジェクト側で定義しておく、フィルタやグルーピングをあらかじめ固定したクエリのテンプレートです。list_saved_queriesツールで一覧を取得でき、頻繁に聞く定型的な問い合わせをメトリクス名とパラメータの組み合わせから毎回組み立てる手間を省けます。

dbt MCPサーバーの他のツールと同時に使えますか

使えます。同じMCPサーバーにDBT_PROJECT_DIR・DBT_PATH(CLI用)とDBT_HOST・DBT_TOKEN・DBT_PROD_ENV_ID(dbt platform用)を両方渡せば、モデルのbuild/compileとSemantic Layerへの問い合わせを1つの接続で切り替えて使えます。CLI操作の手順は冒頭で触れた別記事にまとめています。

remote MCPとself-hostedで使えるツールに違いはありますか

Semantic Layer・SQL・Discovery・Administrative API・Fusionツールはどちらでも使えます。dbt platform CLIコマンドとCodegenツールはself-hosted限定で、remote MCPでは使えません。

まとめ

dbt Semantic Layerは、メトリクスの定義をdbtプロジェクト側に一元化し、list_metricsからquery_metricsまでの7つのツールでClaudeから自然言語のまま照会できるようにします。利用にはdbt platformのStarter/Enterprise-tierアカウントが前提で、DBT_HOST・DBT_TOKEN・DBT_PROD_ENV_IDをself-hosted構成に渡すか、remote MCPをOAuthかトークンで接続します。定期配信するダッシュボードはBIツール側に残し、探索的な問い合わせや一回限りの確認をClaude経由に寄せると、メトリクス定義を二重管理せずに済みます。