--- title: "dbt Semantic Layerの使い方：設定からJDBC・GraphQL・Python SDKで指標を引くまで【2026年版】" url: "https://www.issoh.co.jp/tech/details/19595/" published: 2026-11-11 updated: 2026-11-11 categories: ["データベース"] publisher: "株式会社一創" --- # 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](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs)は、dbt platformの契約が無くても指標の定義とコマンドラインでの照会はできるが、APIと連携機能で指標を動的に引くことはできない、と明記しています。[MetricFlow commands](https://docs.getdbt.com/docs/build/metricflow-commands)の説明をもとに整理すると、違いは次のとおりです。 | 項目 | dbt Core＋mf | dbt platform | | ---------------- | ----------- | ------------- | | コマンド | mf | dbt sl | | 実行場所 | 手元のマシン | dbt platform上 | | JDBC・GraphQL・SDK | 使えない | 使える | | BI・表計算の連携 | 使えない | 12種 | | exports | 使えない | 使える | | 費用 | 無料 | Starter以上 | MetricFlow本体は[dbt-labs/metricflow](https://github.com/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で指標を定義する手順](https://www.issoh.co.jp/tech/details/12323/)で扱いました。 ## dbt platformでの設定手順：環境・認証情報・サービストークン 定義がデプロイされたら、dbt platformの管理画面でSemantic Layerを有効にします。 ### 前提条件：対応DWH6種・デプロイ環境・成功したジョブ実行が1回以上 [Administer the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl)（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つの手順 管理画面の操作は、プロジェクト単位で次の順に進めます。 1. Account settings → Projects で対象プロジェクトを開き、Semantic Layer欄の「Configure Semantic Layer」を選ぶ 2. 使うデプロイ環境を選んで保存する 3. 「Add Semantic Layer credential」でDWHの認証情報を登録する。指標が参照するスキーマへの読み取り権限だけを持つユーザーにする 4. 「Map new service token」で権限を「Semantic Layer Only」と「Metadata Only」にしたトークンを作り、表示された値を控える トークンは作成後に再表示できません。個人のアクセストークンでも認証できますが、その場合は問い合わせが個人の認証情報で実行されます。BIやバッチから使う接続には、退職や異動で止まらない[サービストークン](https://docs.getdbt.com/docs/dbt-apis/service-tokens)を使ってください。Starterで登録できる認証情報はプロジェクトに1つだけで、部門ごとに読めるスキーマを分けるにはEnterprise系の契約が要ります。 ### Environment ID・Host・トークンを連携先へ渡すときの3つの確認点 設定が終わると、Project detailsの画面に接続情報が表示されます。BIの担当者へ渡すのは、Environment ID、Host、トークンの3つです。 Hostはアカウントのリージョンで変わります。[GraphQL API](https://docs.getdbt.com/docs/dbt-apis/sl-graphql)の資料では、北米のマルチテナントが`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](https://docs.getdbt.com/docs/dbt-apis/sl-jdbc)で接続します。ドライバは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](https://docs.getdbt.com/docs/dbt-apis/sl-python)が手軽です。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](https://github.com/dbt-labs/example-semantic-layer-clients)にあります。 ## BI・スプレッドシート・AIエージェントとの連携：公式連携12種とMCPサーバー コードを書かずに指標を使う経路も見ておきます。 ### Power BI・Excel・Google Sheetsなど公式連携12種の選び方 [Available integrations](https://docs.getdbt.com/docs/platform-integrations/avail-sl-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の連携](https://docs.getdbt.com/docs/platform-integrations/semantic-layer/gsheets)は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](https://docs.getdbt.com/docs/dbt-ai/about-mcp)（2026年11月5日更新）によると、dbt platform上のリモート版は全プランで使えますが、提供されるツールはその裏のAPIの契約に従います。Semantic Layerの指標を引くツールを使うには、結局Starter以上が要ります。 手元で動かす版はPyPIの`dbt-mcp`（2.10.1、Python 3.12以上）を`uvx dbt-mcp`で起動する形です。AIが生のテーブルからSQLを推測するのではなく、定義済みの指標を呼ぶので、部署によって売上の数字が変わる事故を抑えられます。会話で数字を引く仕組みが何を前提にしているかは[会話型BIの仕組みと導入判断](https://www.issoh.co.jp/column/details/14675/)で、意味の層を整える考え方は[セマンティックレイヤーの導入判断](https://www.issoh.co.jp/column/details/13790/)で整理しています。 ## saved query・exports・宣言的キャッシュで頻出の指標を速く安く返す設定 同じ切り口の問い合わせが毎日繰り返されるなら、事前に計算して置いておく方が速く、課金も読みやすくなります。 ### saved queryとexportsの定義と本番ジョブで書き出す設定 [saved query](https://docs.getdbt.com/docs/build/saved-queries)は、指標と切り口と条件の組み合わせに名前を付けたものです。`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](https://docs.getdbt.com/docs/use-dbt-semantic-layer/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の違い](https://www.issoh.co.jp/tech/details/19593/)を参照してください。 書き出したテーブルは連携の無いBIからも読めますが、`ref`では参照できず、利用者が別の集計を重ねると定義からずれます。 ### 宣言的キャッシュの条件と、dbt\_sl\_cacheスキーマで権限が効かない落とし穴 [Cache common queries](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache)によると、キャッシュは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?](https://docs.getdbt.com/docs/platform/billing/how-pricing-works)（2026年10月8日更新）の定義では、APIでSQLを生成または実行する成功したリクエストは、データが0行でも最低1件です。計算した指標が複数なら指標ごとに数え、`--compile`でSQLを見るだけでも同じく数えます。失敗した問い合わせと、指標一覧などのメタデータ取得は数えません。exportsは実行時に計上され、書き出したテーブルを読む分は計上されません。 [dbtの料金ページ](https://www.getdbt.com/pricing)では、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 料金の全体像](https://www.issoh.co.jp/column/details/19497/)で試算しています。 ### Semantic Layerを採用する条件と、dbt CoreとOSSのBIで止める場面 採用するのは、同じ売上や粗利の定義を2種類以上の出口で使う場合です。BIとExcel、BIとAIエージェント、社内向けの集計APIといった組み合わせがこれに当たります。出口ごとに計算式を書くと、どこかで必ず数字がずれます。接続先が対応DWHの6種に入っていることも条件です。 見送るのは、出口がBI 1つだけの段階です。この場合はBIに内蔵の意味モデルか、dbtのYAMLを直接読む[Lightdash](https://www.issoh.co.jp/tech/details/6478/)で十分です。dbt CoreとPostgreSQL、DuckDBの構成も同じで、指標の定義と検証はmfで続け、出口が増えた時点でdbt platformへ移ります。どの指標を誰に配るかの設計から、DWH・dbt・BIまでをまとめて整えたい場合は、一創の[データ分析基盤構築・MLOps構築支援](https://www.issoh.co.jp/service/ai/data-platform/)でご相談を受けています。 ## よくある質問 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の使い方](https://www.issoh.co.jp/tech/details/19592/)で解説しています。 ### 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のルート証明書を入れる必要もあります。 ## 関連記事 - [dbtのmarts層とは？3層の分け方とMetricFlowで指標を定義する手順【dbt 1.12対応】](https://www.issoh.co.jp/tech/details/12323/)：Semantic Layerで配る指標の定義手順 - [セマンティックレイヤーとは？意味・仕組みから会話型AI時代の導入判断まで解説](https://www.issoh.co.jp/column/details/13790/)：ツールを選ぶ前の概念と導入判断 - [dbtとは？ELTのTを担う仕組みとdbt Core・Cloudの選び方【2026年版】](https://www.issoh.co.jp/column/details/16548/)：dbt Coreとdbt platformの選び方 - [Lightdash（ライトダッシュ）とは？dbtで指標を定義するOSS BIの料金・AI機能・導入手順【2026年版】](https://www.issoh.co.jp/tech/details/6478/)：dbtのYAMLを直接読むOSSのBI - [dbt Coreの使い方：インストールからprofiles.yml・dbt build・CIまでの手順【1.12対応】](https://www.issoh.co.jp/tech/details/19592/)：定義を書く前のdbt Coreの環境構築 --- 出典: [dbt Semantic Layerの使い方：設定からJDBC・GraphQL・Python SDKで指標を引くまで【2026年版】]()（株式会社一創）