2026.11.11 データベース

dbt docsの使い方：generate・serveでリネージを作り社内に公開する手順【v2対応】

Q: dbt docs serveで社内に公開してもよいですか？

勧めません。公式ドキュメントは dbt docs serve をローカルの開発用途に限っており、1.12系の実装はPython標準のHTTPサーバーで認証もHTTPSもありません。チームに見せるなら、生成したファイルをGitHub Pages（Enterprise Cloudで非公開設定）か、S3とCloudFrontのような認証を掛けられる配信先に置いてください。

Q: dbt docsのリネージに列単位の依存は出せますか？

dbt v2のDocs v2なら出せます。 dbt build --generate-info-schema --static-analysis strict でビルドしてから、 dbt docs generate --no-compile でサイトを作ります。dbt-core 1.12系のDocs v1が表示するのはモデル単位のリネージだけです。列単位の追跡が必要でv2へ移れない場合は、dbt platformのCatalogかデータカタログ製品を検討します。

Q: dbt docs generateが遅いときはどうすればよいですか？

遅いのは多くの場合、DWHへのメタデータ問い合わせです。 --select で対象を100ノード未満に絞るとWHERE句付きの問い合わせになり、DWH側で絞り込まれます。開発中にリネージだけ見たいなら --empty-catalog で問い合わせ自体を省けます。直前にコンパイル済みなら --no-compile も併用してください。

dbt docsの使い方：generate・serveでリネージを作り社内に公開する手順【v2対応】

dbt docsは、モデルの説明・列・テスト・リネージを1つのWebサイトにまとめる機能です。2026年11月時点では、dbt-core 1.12系の「Docs v1」と、dbt v2の「Docs v2」で生成物も既定のポートも違います。この記事では公式ドキュメントとdbtのソースコードをもとに、descriptionとdocsブロックの書き方、dbt docs generateとdbt docs serveのフラグ、列レベルのリネージの出し方、GitHub PagesやS3とCloudFrontで社内に公開する手順を、コピーして使える形で整理しました。

まとめ：dbt docsは版で生成物が変わり、社内公開は配信先と認証で決まる

手元で確かめるだけなら、dbt docs generateのあとにdbt docs serveを打てばブラウザが開きます。v1は8080番、v2は8580番です。

社内に見せる段階ではdbt docs serveを使いません。公式ドキュメントはこのコマンドをローカルの開発用途に限定しています。生成した静的ファイルを、アクセス制御のできる配信先に置きます。

配信先の選び方は単純です。GitHub Enterprise Cloudを契約していればGitHub Pagesを非公開にでき、それ以外はS3とCloudFrontで認証を掛けます。dbt platformのStarter以上を契約しているなら、自前の公開はやめてCatalogと閲覧専用シートに任せる方が保守の手間がかかりません。

dbt docsの生成物を比較：dbt-core 1.12系とdbt v2の違い

手順に入る前に、手元のdbtがどちらの系統かを確かめます。dbt --versionで「Core: 1.12.x」と出ればv1、2.0系ならv2です。入れ分けの手順はdbt Coreの使い方で解説しています。

Docs v1のJSONとDocs v2のParquet索引を読む仕組み

About dbt docs commandsによると、v1のdbt docs generateはサイト本体のindex.htmlをtarget/へコピーし、プロジェクトをコンパイルしてmanifest.jsonを書き、DWHのメタデータを問い合わせてcatalog.jsonを作ります。ブラウザはこの2つのJSONを丸ごと読み込みます。

v2の生成物はJSONではなくParquetの索引です。ブラウザがDuckDB-WASMでParquetを直接読むので、モデル数の多い大きなプロジェクトでも表示が重くなりにくい作りです。dbt Information Schemaは、manifest.jsonとcatalog.jsonで合計約70MBのプロジェクトが約5MBに収まる例を示しています。

項目	Docs v1（dbt-core 1.12系）	Docs v2（dbt v2）
主な生成物	HTML本体・2種のJSON	HTML本体・アセット・Parquet索引
serveの既定ポート	8080	8580
列レベルのリネージ	なし	フラグ指定で表示
1ファイル化	–static	–output-dirでフォルダ出力

表のHTML本体は両系統ともindex.htmlです。v1の2種のJSONはmanifest.jsonとcatalog.json、v2のアセットはassets/、Parquet索引はindex/です。既存の公開手順がtarget/を配信先へ移すだけなら、v2でもそのまま動きます。公式ドキュメントはv2の出力先をv1と同じtarget/の配置にそろえたと説明しています。

dbt platformのv2ジョブで静的サイトからCatalogへ切り替わる条件

dbt platformのジョブでv2を使う場合、ジョブの手順にdbt docs generateを足しても静的サイトは作られません。dbtは代わりにdbt compile --write-catalogを実行し、Catalogを見るよう案内します。Docs v2はローカルと自前のパイプライン専用で、dbt platformでは提供されていません。

dbt platform上で過去に作ったdocsのジョブをv2へ移すと、index.htmlを前提にした後続の公開処理が空振りします。移行の前に、そのジョブの成果物を誰が見ているかを洗い出しておきます。

descriptionとdocsブロックをYAMLに書き、モデルと列の説明を整える手順

dbt docsに表示される説明文は、テストと同じYAMLに書きます。コマンドを打つ前に、ここを整えておかないと空の画面が並ぶだけになります。

schema.ymlの説明をdoc関数でMarkdownに分けて管理する書き方

About documentationのとおり、モデルと列にはdescription:を足します。数行を超える説明は.mdファイルのdocsブロックに逃がし、YAMLからはdoc()関数で参照します。

# models/marts/_marts.yml
models:
  - name: fct_daily_sales
    description: '{{ doc("fct_daily_sales") }}'
    columns:
      - name: order_date
        description: 注文日（JST）。返品の計上日ではない
        data_tests:
          - not_null
      - name: sales
        description: status が completed の注文の税込金額の合計

-- models/marts/fct_daily_sales.md
{% docs fct_daily_sales %}
日別の売上集計。毎朝6時の本番ジョブで更新する。
- 返品は含めない（返品は fct_daily_returns を参照）
- 問い合わせ先：データ基盤チーム
{% enddocs %}

docsブロックの名前に使えるのは英数字とアンダースコアだけで、数字から始められません。1.12からはallow_jinja_file_extensions: trueを設定すると.md.j2などの拡張子も使えます。

overviewブロックで社内向けトップページを差し替える設定

何も設定しないと、dbt docsのトップページにはdbt自身の説明が出ます。社内に公開するなら、__overview__という名前のdocsブロックで差し替え、命名規則・更新時刻・問い合わせ先を最初に見せます。

# dbt_project.yml（docs/ フォルダに置く場合だけ必要）
docs-paths: ["docs"]

-- docs/overview.md
{% docs __overview__ %}
# 販売データ基盤
- stg_ は取り込み直後の整形、fct_ と dim_ が分析用の表です
- 本番の更新は毎朝6時。遅延は #data-infra チャンネルで告知します
{% enddocs %}

docs-pathsを設定していなければ、dbtはmodelsなどのリソース用フォルダからdocsブロックを探します。models/overview.mdに置けば設定は要りません。逆にdocs-pathsを書くとそのフォルダしか探さなくなるので、モデル横の.mdが見つからなくなる点に気をつけます。

persist_docsで説明をDWHの列コメントにも書き戻す設定と対応アダプター

BIツールやSQLクライアントから直接テーブルを見る人には、dbt docsのサイトは届きません。persist_docsを有効にすると、descriptionがテーブルと列のコメントとしてDWHにも書き込まれます。

# dbt_project.yml
models:
  shop_dbt:
    marts:
      +persist_docs:
        relation: true
        columns: true

対応するのはPostgreSQL・Redshift・Snowflake・BigQuery・Databricks・Apache Spark・Starburst Galaxyです。sourcesには効きません。Snowflakeではca_net_ht_Nのように大文字と小文字が混ざった列名だとコメントが付かないため、YAMLの列名を小文字にそろえるかquote: trueを指定します。

dbt docs generateとserveをローカルで動かし、リネージを確かめる

説明を書いたら、手元でサイトを作って表示を確かめます。v1とv2でフラグが違うので、分けて書きます。

v1のdocs generateの3段階と生成対象・問い合わせを絞るフラグ

v1では、先にdbt buildでテーブルを作っておきます。catalog.jsonはDWHに実在するテーブルの列を読むため、未作成のモデルはYAMLに書いた列しか表示されません。

dbt build                                   # テーブルとビューを先に作る
dbt docs generate                           # index.html・manifest.json・catalog.json
dbt docs generate --select +fct_daily_sales # catalogを指定モデルと上流に絞る
dbt docs generate --empty-catalog           # DWHに問い合わせない（開発中のリネージ確認用）
dbt docs generate --no-compile              # 再コンパイルを省く
dbt docs generate --static                  # target/static_index.html を1ファイルで出力

--selectで絞るのはcatalog.jsonだけで、manifest.jsonは全体のままです。公式ドキュメントによると、選んだノードが100未満ならDWH側でWHERE句を使って絞り込み、100以上なら対象スキーマを全件読んでからメモリ上で絞ります。--staticはmanifestとcatalogを埋め込んだHTMLを書き出し、1.12系のソースコードではファイル名がstatic_index.htmlです。メールやファイル共有で1枚だけ渡したいときに使います。

dbt docs serveの8080・8580と待ち受け先・ポートの指定

v1のdbt docs serveはtarget/を起点に8080番でWebサーバーを立て、既定のブラウザを開きます。1.8.1以降は待ち受けが127.0.0.1なので、同じネットワークの別の端末からは見えません。

# v1（dbt-core 1.12系）
dbt docs serve --port 8001 --no-browser
dbt docs serve --host ""          # 全インターフェースで待ち受け（検証時のみ）

# v2（dbt v2）
dbt docs serve --port 8081
dbt docs serve --target-path ~/work/internal-analytics/target

v2の既定ポートは8580です。v2のserveはサイトが無いか索引より古いと自動で作り直すため、generateを打ち忘れても動きます。v1はcatalog.jsonが無いとエラーで止まります。

Docs v2の列レベルリネージに必要なビルドのフラグと静的解析の設定

Docs v2の目玉は列単位のリネージです。ただし既定では出ません。ビルドの段階でdbt Information Schemaを書き出し、静的解析をstrictにしてから、コンパイルを省いてサイトを作ります。

dbt build --generate-info-schema --static-analysis strict
dbt docs generate --no-compile --output-dir site
dbt docs serve

メタデータはtarget/info_schema/v1/にParquetで書かれ、DWHの計算資源は使いません。フラグを付けずに作ったサイトでは、列リネージの画面が空表示ではなく非表示になります。「出ない」と迷ったら、まずビルドのフラグを疑います。2026年10月公開の一部の解説記事には--write-indexという別のフラグ名が出てきますが、11月時点の公式ドキュメントの表記は--generate-info-schemaです。手元の版ではdbt build --helpで確かめてください。静的解析の厳しさを上げると型の合わないSQLが解析段階で落ちるので、移行の注意点はdbt Fusionとはを参照してください。

社内公開：GitHub ActionsのPages配信とS3・CloudFrontの認証

手元で表示を確かめたら、チームで見られる場所へ置きます。ここで手を抜くと、テーブル定義やSQLが社外から読める状態になります。

docs serveを本番に使わず、公開するファイルをtarget全体から絞る

View documentationは、dbt docs serveをローカルの開発用途だけに使うよう注意しています。1.12系のserve.pyの中身は、Python標準のSimpleHTTPRequestHandlerを立てているだけです。認証もHTTPSもありません。

配信先に置くファイルも絞ります。v1で必要なのはindex.html・manifest.json・catalog.jsonの3つです。target/にはcompiled/とrun/に展開済みのSQL、run_results.jsonに実行結果も入っており、まとめて上げると見せる必要のないものまで公開されます。v2は--output-dir siteで出したsite/だけを上げます。

GitHub ActionsでビルドしPagesへデプロイするワークフローの例

本番のテーブルがすでにある前提で、mainブランチへのマージごとにdocsを作り直してGitHub Pagesへ出す例です。dbt docs generateはテーブルを作らず、既存のテーブルのメタデータを読むだけなので、本番ジョブとは別に流せます。カスタムワークフローでのPages公開の手順に沿い、upload-pages-artifactとdeploy-pagesを使います。

# .github/workflows/dbt-docs.yml
name: dbt-docs
on:
  push:
    branches: [main]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DBT_ENV_SECRET_PG_PASSWORD: ${{ secrets.DBT_PG_PASSWORD }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: "3.12"
      - run: pip install "dbt-core~=1.12.0" "dbt-postgres~=1.11.0"
      - run: dbt deps
      - run: dbt docs generate --target prod --profiles-dir .
      - run: |
          mkdir -p site
          cp target/index.html target/manifest.json target/catalog.json site/
      - uses: actions/upload-pages-artifact@v5
        with:
          path: site
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

リポジトリの設定でPagesの公開元を「GitHub Actions」にしてから流します。アクションの版は2026年11月11日時点の最新リリースに合わせました。DWHの資格情報はDBT_ENV_SECRET_で始まる環境変数で渡し、ログに出ても伏せ字になるようにしています。

Pagesを社外に見せない条件とS3・CloudFrontでの配信の分かれ目

GitHub Pagesの既定は全公開です。Pagesの公開範囲の変更によると、閲覧をリポジトリの読み取り権限を持つ人に限れるのは、GitHub Enterprise Cloudの組織が所有するprivateかinternalのリポジトリだけです。FreeやTeamのプランで前節のワークフローを流すと、テーブル定義が誰でも読める状態で公開されます。

Enterprise Cloudが無いなら、非公開のS3バケットに置き、CloudFrontのオリジンアクセスコントロール（OAC）経由でだけ読ませます。Restrict access to an Amazon S3 originのバケットポリシーと、更新時のコマンドは次の形です。

# バケットポリシー（CloudFrontのディストリビューションからの読み取りだけを許可）
{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {"Service": "cloudfront.amazonaws.com"},
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::example-dbt-docs/*",
    "Condition": {"StringEquals": {
      "AWS:SourceArn": "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE"
    }}
  }]
}

# docsの更新（CIの最後に実行）
aws s3 sync site/ s3://example-dbt-docs/ --delete
aws cloudfront create-invalidation --distribution-id EDFDVBD6EXAMPLE --paths "/*"

OACはバケットへの直アクセスを塞ぐだけで、CloudFrontのURLを知っていれば誰でも開けます。閲覧者を絞るには、AWS WAFで社内の送信元IPだけを許可するか、社内のIDプロバイダーと連携した認証を前段に置きます。どちらを選ぶかは閲覧者が社外から接続するかで決まり、在宅勤務の閲覧者がいるならIP制限では足りません。

dbt docsの自前公開を続ける条件とCatalogやデータカタログへ移る判断

公開の仕組みを作ったあとで、残るのは誰が保守するかです。静的サイトのまま続けるか、別の仕組みへ移るかをここで決めます。

静的サイトで足りる規模と閲覧専用シートのCatalogを選ぶ場面

自前公開で足りるのは、閲覧者がdbtを書くエンジニアとアナリスト中心で、CIの保守を引き受ける人が1人以上いる場合です。上のワークフローを置けば、追加の費用はDWHへのメタデータ問い合わせと配信費だけで済みます。

事業部門の担当者まで閲覧者に含めるなら、自前公開は勧めません。認証基盤との連携、アクセス権の棚卸し、更新が止まったときの監視まで自分たちの管理範囲になるためです。dbt platformのStarter・Enterprise・Enterprise+では、ジョブの実行ごとにCatalogが自動で更新され、閲覧専用シートを必要な数だけ足せます。費用の見積もりはdbt 料金の全体像が試算の参考です。docsの公開を含めたデータ基盤の設計と運用を任せたい場合は、一創のデータ分析基盤構築・MLOps構築支援でご相談を受けています。

v2のDocs v2を閉域網で使えない理由とOpenMetadataへ移る条件

Docs v2には見落としやすい前提があります。View documentationによると、ブラウザは実行時にDuckDB-WASMをCDNから読み込むため、閲覧者の端末にはCDNへの外向き通信が要ります。インターネットへ出られない閉域網の端末では、静的ファイルを社内に置いても表示できません。その環境ではv1のDocsを使い続けるのが現実的です。

dbt以外のデータソース、たとえば業務システムのDBやBIのダッシュボードまで1か所で探したくなったら、dbt docsの守備範囲を超える要件です。OpenMetadataの構成と導入手順のようなデータカタログ製品へ移り、dbtはmanifest.jsonとcatalog.jsonを取り込ませる側に回ります。データカタログを入れるかどうかの判断はデータカタログとはで整理しています。

よくある質問

dbt docsを使い始めるときによく聞かれる質問に答えます。

dbt docsは無料で使えますか？

無料です。dbt-core 1.12系のDocs v1も、dbt v2のDocs v2も、ローカルでの生成と自前の公開に費用はかかりません。かかるのは、catalog.jsonを作るときにDWHへ投げるメタデータ問い合わせの料金と、配信先のS3やCloudFrontの利用料です。dbt platformのCatalogで共有する場合は、Starter以上のプランの契約が要ります。

dbt docs serveで社内に公開してもよいですか？

勧めません。公式ドキュメントはdbt docs serveをローカルの開発用途に限っており、1.12系の実装はPython標準のHTTPサーバーで認証もHTTPSもありません。チームに見せるなら、生成したファイルをGitHub Pages（Enterprise Cloudで非公開設定）か、S3とCloudFrontのような認証を掛けられる配信先に置いてください。

dbt docsのリネージに列単位の依存は出せますか？

dbt v2のDocs v2なら出せます。dbt build --generate-info-schema --static-analysis strictでビルドしてから、dbt docs generate --no-compileでサイトを作ります。dbt-core 1.12系のDocs v1が表示するのはモデル単位のリネージだけです。列単位の追跡が必要でv2へ移れない場合は、dbt platformのCatalogかデータカタログ製品を検討します。

dbt docs generateが遅いときはどうすればよいですか？

遅いのは多くの場合、DWHへのメタデータ問い合わせです。--selectで対象を100ノード未満に絞るとWHERE句付きの問い合わせになり、DWH側で絞り込まれます。開発中にリネージだけ見たいなら--empty-catalogで問い合わせ自体を省けます。直前にコンパイル済みなら--no-compileも併用してください。

dbt docsとdbt Catalogの違いは何ですか？

dbt docsは自分で生成して配信する静的サイトで、dbt CoreでもdbtのDeveloperプランでも使えます。Catalogはdbt platformのStarter以上のプランに含まれ、ジョブの実行ごとに自動で更新されるうえ、実行結果や利用状況も見られる点が違いです。dbt CoreとCloud（dbt platform）のどちらを選ぶかの判断軸はdbtとは：dbt Core・Cloudの選び方で整理しています。