2026.11.11 データベース

dbt Semantic Layerの使い方：設定からJDBC・GraphQL・Python SDKで指標を引くまで【2026年版】

Q: Semantic Layerの指標を変更したら何を実行すればよいですか？

開発中は dbt parse で反映され、モデルの再作成は要りません。本番では、Semantic Layerに設定したデプロイ環境でジョブを実行し、新しい定義をデプロイする手順です。CIのジョブに dbt sl validate を入れておくと、指標が参照する列を消すような変更をマージ前に止められます。exportsとキャッシュを使っている場合は、saved queryのジョブも合わせて流します。

dbt Semantic Layerの使い方：設定からJDBC・GraphQL・Python SDKで指標を引くまで【2026年版】

dbt Semantic Layerは、dbtプロジェクトに書いた指標の定義を、BIツールやスプレッドシート、自作のアプリへAPIで配る仕組みです。定義を担うMetricFlowは無料で使えますが、APIで外へ配る部分はdbt platformのStarter以上の有料プランに限られます。この記事では2026年11月時点の公式ドキュメントをもとに、dbt platformでの設定、dbt sl・JDBC・GraphQL・Python SDKのコード例、公式連携とMCP、exportsとキャッシュ、queried metricの数え方から見た採否の判断までを整理しました。

まとめ：dbt Semantic Layerは定義を無料で書き、配信を有料プランで受け持つ構成

指標の定義はdbt CoreとMetricFlowの組み合わせで書けます。ここまでは費用がかかりません。

BIやアプリから同じ指標を引けるようにするのがSemantic Layerで、dbt platformのデプロイ環境を1つ選び、データウェアハウスの読み取り用認証情報とサービストークンを登録して使います。取得経路はJDBC（Arrow Flight SQL）・GraphQL・Python SDKの3つと、Tableau・Power BI・Google Sheets・Excelなど12種の公式連携です。

料金は「計算した指標の数」で数えます。1回の問い合わせで指標を2つ取れば2件です。Starterの上限は月5,000件なので、利用者の多いダッシュボードをそのまま載せると不足します。2種類以上のツールで同じ指標を使う組織には向き、BIが1つだけならBI側の定義で足ります。

Semantic Layerの構成：MetricFlowの定義とAPI配信の分担

最初に、どこまでが無料で、どこからが有料プランの機能かを切り分けます。

無料のmfでできる範囲と、Starter以上でしか使えないAPI・連携の境界

公式のSemantic Layer FAQsは、dbt platformの契約が無くても指標の定義とコマンドラインでの照会はできるが、APIと連携機能で指標を動的に引くことはできない、と明記しています。MetricFlow commandsの説明をもとに整理すると、違いは次のとおりです。

項目	dbt Core＋mf	dbt platform
コマンド	mf	dbt sl
実行場所	手元のマシン	dbt platform上
JDBC・GraphQL・SDK	使えない	使える
BI・表計算の連携	使えない	12種
exports	使えない	使える
費用	無料	Starter以上

MetricFlow本体はdbt-labs/metricflowで公開されており、PyPIの最新はmetricflow 0.213.0とdbt-metricflow 0.15.0（いずれも2026年9月10日公開）です。定義の検証までなら、この無料の範囲で完結します。

dbt 1.12の新YAML仕様で書く最小の指標定義とmartsモデル

Semantic Layerが配るのは、martsモデルに付けた指標です。dbt 1.12以降の新仕様では、モデルの定義にsemantic_modelを同居させ、列ごとにentityとdimensionを付けます。

# models/marts/_marts.yml（dbt 1.12以降の新仕様）
models:
  - name: fct_orders
    semantic_model:
      enabled: true
    agg_time_dimension: ordered_at
    columns:
      - name: order_id
        entity:
          type: primary
          name: order
      - name: customer_id
        entity:
          type: foreign
          name: customer
      - name: ordered_at
        granularity: day
        dimension:
          type: time
    metrics:
      - name: revenue
        label: 売上
        type: simple
        agg: sum
        expr: amount
      - name: order_count
        label: 注文数
        type: simple
        agg: count
        expr: order_id

この記事のコード例は、上のrevenueとorder_count、顧客側にregionという区分の列がある前提で書いています。time spineの作り方、ratioやcumulativeなど5種類の指標、旧仕様（measures）からの書き換えはdbtのmarts層とMetricFlowで指標を定義する手順で扱いました。

dbt platformでの設定手順：環境・認証情報・サービストークン

定義がデプロイされたら、dbt platformの管理画面でSemantic Layerを有効にします。

前提条件：対応DWH6種・デプロイ環境・成功したジョブ実行が1回以上

Administer the Semantic Layer（2026年8月18日更新）が挙げる前提は、Starter・Enterprise・Enterprise+のいずれかの契約、Snowflake・BigQuery・Databricks・Redshift・Postgres・Trinoのいずれかの接続先、設定する環境での成功した実行が1回以上、の3点です。

見落としやすい制約が2つあります。問い合わせの対象はデプロイ環境だけで、開発環境への問い合わせは「coming soon」の扱いです。本番用の認証情報にはSSOを使えないため、DWH側にSemantic Layer専用のサービスユーザーを用意しておきます。DuckDBとSQL Serverは一覧に無く、これらを使っている場合はmfでの検証までが上限です。

Configure画面から認証情報とサービストークンを作る4つの手順

管理画面の操作は、プロジェクト単位で次の順に進めます。

Account settings → Projects で対象プロジェクトを開き、Semantic Layer欄の「Configure Semantic Layer」を選ぶ
使うデプロイ環境を選んで保存する
「Add Semantic Layer credential」でDWHの認証情報を登録する。指標が参照するスキーマへの読み取り権限だけを持つユーザーにする
「Map new service token」で権限を「Semantic Layer Only」と「Metadata Only」にしたトークンを作り、表示された値を控える

トークンは作成後に再表示できません。個人のアクセストークンでも認証できますが、その場合は問い合わせが個人の認証情報で実行されます。BIやバッチから使う接続には、退職や異動で止まらないサービストークンを使ってください。Starterで登録できる認証情報はプロジェクトに1つだけで、部門ごとに読めるスキーマを分けるにはEnterprise系の契約が要ります。

Environment ID・Host・トークンを連携先へ渡すときの3つの確認点

設定が終わると、Project detailsの画面に接続情報が表示されます。BIの担当者へ渡すのは、Environment ID、Host、トークンの3つです。

Hostはアカウントのリージョンで変わります。GraphQL APIの資料では、北米のマルチテナントがsemantic-layer.cloud.getdbt.com、EMEAがsemantic-layer.emea.dbt.com、APACがsemantic-layer.au.dbt.comです。シングルテナントでは個別のアクセスURLの前にsemantic-layer.が付きます。資料の例を写さず、画面に出た値を使ってください。

連携先がGraphQLを使うツールなら、JDBC URLではなくGraphQLのHostを渡します。設定を削除すると全トークンのひも付けが外れ、すべての問い合わせが失敗する点も運用手順書に書いておきます。

定義済みの指標をdbt sl・JDBC・GraphQL・SDKで取得するコード例

同じ指標を4つの経路で取り出す例です。

dbt sl queryで定義を確かめるコマンドと既定の100行上限

dbt platform CLIやStudio IDEではdbt slで問い合わせます。外部ツールをつなぐ前に、ここで指標と切り口の名前を確かめておくと、連携先での名前の打ち間違いを防げます。

# 定義済みの指標と、指標ごとに使える切り口を一覧する
dbt sl list metrics
dbt sl list dimensions --metrics revenue

# 月別売上を新しい順に12行取得する
dbt sl query --metrics revenue,order_count --group-by metric_time --order-by -metric_time --limit 12

# 実行せずに生成SQLだけを見る
dbt sl query --metrics revenue --group-by metric_time --compile

公式ドキュメントの注記では、dbt platform CLIのqueryは既定で100行までしか返しません。--start-timeと--end-timeはdbt platformとdbt v2では使えないため、期間は--whereで絞ります。指標の定義を変えたあとはモデルを作り直す必要はなく、少なくともdbt parseを実行すればSemantic Layerに反映されます。

JDBCの接続URLとsemantic_layer.queryの書き方

DataGripのような汎用のJDBCクライアントや、JDBCに対応したBIからはJDBC APIで接続します。ドライバはArrow Flight SQLの12.0.0以上が必要です。

-- 接続URL（環境IDとトークンは自社の値に置き換える）
-- jdbc:arrow-flight-sql://semantic-layer.cloud.getdbt.com:443?&environmentId=123456&token=YOUR_TOKEN

-- 月別・地域別の売上と注文数
select * from {{
  semantic_layer.query(
    metrics=['revenue', 'order_count'],
    group_by=[Dimension('metric_time').grain('month'), 'customer__region'],
    where=["{{ Dimension('customer__region') }} = 'kanto'"],
    order_by=['-revenue'],
    limit=12
  )
}}

-- 指標の一覧（メタデータの取得）
select * from {{ semantic_layer.metrics() }}

customer__regionは「customerエンティティ側のregion列」という意味です。whereは文字列1本でも書けますが、公式は本番では条件をリストで渡す形を勧めています。DWHへの条件の押し込みが効くためです。SQLの中でrefは使えず、dbtのマクロで指標を計算している場合はそのロジックを指標の定義側へ移す必要があります。

GraphQL APIのcreateQueryと結果を取りに行くポーリング

GraphQLは非同期です。まずcreateQueryで問い合わせを登録してIDを受け取り、次にそのIDで状態と結果を取りに行きます。

# 1. 問い合わせを登録して queryId を受け取る
curl -s https://semantic-layer.cloud.getdbt.com/api/graphql \
  -H "Authorization: Bearer $DBT_SL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"mutation { createQuery(environmentId: 123456, metrics: [{name: \"revenue\"}], groupBy: [{name: \"metric_time\"}]) { queryId } }"}'

# 2. status が SUCCESSFUL か FAILED になるまで間隔を空けて繰り返す
curl -s https://semantic-layer.cloud.getdbt.com/api/graphql \
  -H "Authorization: Bearer $DBT_SL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ query(environmentId: 123456, queryId: \"QueryID_xxxx\") { status error totalPages jsonResult(encoded: false) } }"}'

結果の既定はArrow形式のバイト列で、jsonResultも既定ではbase64で符号化されています。encoded: falseを付けると生のJSONが返るので、動作確認ではこちらが読みやすいです。1ページは1024行までで、超える分はpageNumを指定して取ります。

dbt-sl-sdkで指標をpyarrowテーブルとして受け取る実装

PythonのアプリやノートブックからはPython SDKが手軽です。GraphQLのポーリングとArrowの復号をSDKが引き受けます。

# pip install "dbt-sl-sdk[sync]" pandas
import os
from dbtsl import SemanticLayerClient

client = SemanticLayerClient(
    environment_id=int(os.environ["DBT_SL_ENV_ID"]),
    auth_token=os.environ["DBT_SL_TOKEN"],
    host="semantic-layer.cloud.getdbt.com",
)

with client.session():
    table = client.query(
        metrics=["revenue", "order_count"],
        group_by=["metric_time"],
    )
    print(table.to_pandas().tail())

戻り値はpyarrowのテーブルで、pandasやpolarsは別途入れます。PyPIの最新は0.13.4（2026年5月27日公開）で、対応はPython 3.9以上3.14未満です。FastAPIのような非同期のWebフレームワークではdbt-sl-sdk[async]を入れ、AsyncSemanticLayerClientを使ってください。セッションはリクエストごとに作らず、アプリ全体で1つを使い回す形が公式の推奨です。SDKは利用環境の情報をdbt Labsへ送るため、止めたい場合はPLATFORM.anonymous = Trueを設定します。他言語の例はexample-semantic-layer-clientsにあります。

BI・スプレッドシート・AIエージェントとの連携：公式連携12種とMCPサーバー

コードを書かずに指標を使う経路も見ておきます。

Power BI・Excel・Google Sheetsなど公式連携12種の選び方

Available integrations（2026年9月29日更新）に載っているのは、Power BI・Tableau・Google Sheets・Microsoft Excel・Omni・Dot・Hex・Klipfolio PowerMetrics・Mode・Push.ai・Sigma（プレビュー）・Steepの12種です。最初の4つはdbtの公式ドキュメント内に設定手順があり、残りは各ベンダーの資料を参照します。

国内の事業会社で使われやすいのはExcelとGoogle Sheetsです。経理や営業企画の担当者が、定義どおりの売上を表計算に直接取り込める仕組みです。Google Sheetsの連携はHost・環境ID・トークンで認証し、dbt側でIP制限を掛けている場合はGoogleのIPアドレスを許可しないと接続に失敗します。一覧に無いツールでも、Arrow Flight SQLの12.0.0以上に対応していればJDBCでつなげます。

dbt MCPサーバー経由でClaudeなどのAIに定義済みの指標を引かせる構成

AIに数字を答えさせるときの入口として、dbt MCPサーバーも選択肢の1つです。About dbt MCP server（2026年11月5日更新）によると、dbt platform上のリモート版は全プランで使えますが、提供されるツールはその裏のAPIの契約に従います。Semantic Layerの指標を引くツールを使うには、結局Starter以上が要ります。

手元で動かす版はPyPIのdbt-mcp（2.10.1、Python 3.12以上）をuvx dbt-mcpで起動する形です。AIが生のテーブルからSQLを推測するのではなく、定義済みの指標を呼ぶので、部署によって売上の数字が変わる事故を抑えられます。会話で数字を引く仕組みが何を前提にしているかは会話型BIの仕組みと導入判断で、意味の層を整える考え方はセマンティックレイヤーの導入判断で整理しています。

saved query・exports・宣言的キャッシュで頻出の指標を速く安く返す設定

同じ切り口の問い合わせが毎日繰り返されるなら、事前に計算して置いておく方が速く、課金も読みやすくなります。

saved queryとexportsの定義と本番ジョブで書き出す設定

saved queryは、指標と切り口と条件の組み合わせに名前を付けたものです。exportsを足すと、その結果をDWHにテーブルかビューとして書き出せます。

# models/marts/_saved_queries.yml
saved_queries:
  - name: monthly_revenue_by_region
    label: 地域別の月次売上
    config:
      cache:
        enabled: true
    query_params:
      metrics:
        - revenue
        - order_count
      group_by:
        - "TimeDimension('metric_time', 'month')"
        - "Dimension('customer__region')"
    exports:
      - name: monthly_revenue_by_region
        config:
          export_as: table
          schema: analytics_exports

本番のジョブで書き出すには、Write queries with exportsのとおり、Deploy → Environments の環境変数にDBT_ENGINE_EXPORT_SAVED_QUERIESをTRUEで登録します（dbt v1.11以降）。そのうえでジョブにdbt build --resource-type saved_queryを入れます。開発環境のdbt sl exportは、Studio IDEやdbt v2の環境では使えず、dbt buildに置き換わります。v2の位置づけはdbt Fusion（dbt v2）とCoreの違いを参照してください。

書き出したテーブルは連携の無いBIからも読めますが、refでは参照できず、利用者が別の集計を重ねると定義からずれます。

宣言的キャッシュの条件と、dbt_sl_cacheスキーマで権限が効かない落とし穴

Cache common queriesによると、キャッシュは2種類です。結果キャッシュはDWH標準の仕組みに乗るため設定は要りません。宣言的キャッシュは、上のYAMLのようにcache.enabled: trueとexportsの両方を書いたsaved queryを対象に、ジョブの実行時に事前計算します。宣言的キャッシュを使えるのはEnterpriseとEnterprise+だけです。

注意が要るのは権限です。キャッシュはdbt_sl_cacheという専用スキーマにデプロイ用の認証情報で作られ、キャッシュから返す場合はクエリ時のセキュリティの文脈が適用されません。部門ごとに認証情報を分けて読める行を絞っていても、キャッシュに載せた指標は別部門のトークンからも同じ結果が返る前提で設計してください。機微な指標はキャッシュの対象から外すのが安全です。上流のモデルが更新されるとキャッシュは無効になり、その間はDWHへ直接問い合わせます。

queried metricの数え方と料金：Starterの月5,000件で足りるかの判断

採用を決める前に、課金の単位で利用量を見積もります。

指標2つの問い合わせは2件、メタデータの取得は0件という数え方

How does dbt pricing work?（2026年10月8日更新）の定義では、APIでSQLを生成または実行する成功したリクエストは、データが0行でも最低1件です。計算した指標が複数なら指標ごとに数え、--compileでSQLを見るだけでも同じく数えます。失敗した問い合わせと、指標一覧などのメタデータ取得は数えません。exportsは実行時に計上され、書き出したテーブルを読む分は計上されません。

dbtの料金ページでは、Starterは1ユーザー月額100ドルで開発者席5つ・1プロジェクト、queried metricsは月5,000件です。EnterpriseとEnterprise+は月20,000件です。仮に指標4つのダッシュボードを20人が1日3回開き、営業日が22日あれば、4×20×3×22＝5,280件となり、Starterの枠を超える計算になる点に注意してください。BI側のキャッシュでAPIへの問い合わせが減るかはツールごとに違うため、試用期間に実際の件数を測ってから契約を決めます。プラン全体の費用感はdbt 料金の全体像で試算しています。

Semantic Layerを採用する条件と、dbt CoreとOSSのBIで止める場面

採用するのは、同じ売上や粗利の定義を2種類以上の出口で使う場合です。BIとExcel、BIとAIエージェント、社内向けの集計APIといった組み合わせがこれに当たります。出口ごとに計算式を書くと、どこかで必ず数字がずれます。接続先が対応DWHの6種に入っていることも条件です。

見送るのは、出口がBI 1つだけの段階です。この場合はBIに内蔵の意味モデルか、dbtのYAMLを直接読むLightdashで十分です。dbt CoreとPostgreSQL、DuckDBの構成も同じで、指標の定義と検証はmfで続け、出口が増えた時点でdbt platformへ移ります。どの指標を誰に配るかの設計から、DWH・dbt・BIまでをまとめて整えたい場合は、一創のデータ分析基盤構築・MLOps構築支援でご相談を受けています。

よくある質問

dbt Semantic Layerを検討するときによく聞かれる質問に答えます。

dbt Semantic Layerは無料で使えますか？

APIと連携機能は無料では使えません。無料のDeveloperプランには含まれず、Starter以上の契約が必要です。一方、指標をYAMLで定義し、mfコマンドで手元から問い合わせるところまでは、dbt CoreとMetricFlowで費用をかけずに行えます。dbt platformにはStarterの試用期間があり、その間もSemantic Layerを設定できると公式ドキュメントに記載があります。

MetricFlowとdbt Semantic Layerの違いは何ですか？

MetricFlowは指標の定義を読み、SQLを組み立てるエンジンです。dbt Semantic Layerは、そのMetricFlowをdbt platform上で動かし、JDBC・GraphQL・Python SDKと12種の連携で外部へ配るサービスです。指標の定義の書き方はどちらも同じなので、mfで検証した定義をそのままdbt platformへ載せられます。

dbt Semantic LayerはPostgreSQLやDuckDBで使えますか？

PostgreSQLは対応しています。2026年11月時点の対応はSnowflake・BigQuery・Databricks・Redshift・Postgres・Trinoの6種で、DuckDBとSQL Serverは含まれていません。DuckDBではmfでの定義と検証までにとどめ、配信が必要になった段階で対応DWHへの移行を合わせて検討します。DuckDBでのdbtの動かし方はdbt Coreの使い方で解説しています。

Semantic Layerの指標を変更したら何を実行すればよいですか？

開発中はdbt parseで反映され、モデルの再作成は要りません。本番では、Semantic Layerに設定したデプロイ環境でジョブを実行し、新しい定義をデプロイする手順です。CIのジョブにdbt sl validateを入れておくと、指標が参照する列を消すような変更をマージ前に止められます。exportsとキャッシュを使っている場合は、saved queryのジョブも合わせて流します。

dbt Semantic Layerの接続でFailed ALPNのエラーが出るのはなぜですか？

社内のプロキシやVPNがTLSの通信を中継していることが原因です。JDBC APIの資料は、ZscalerやCheck Pointなどの製品がTLSのハンドシェイクを妨げる例を挙げ、プロキシでALPNを許可するか、dbtのドメインを中継の例外に加えるよう案内しています。自作のJavaアプリから接続する場合は、JavaのトラストストアにAWSのルート証明書を入れる必要もあります。