dbt モデルの access 設計ガイド: public / protected / private の使い分け

dbt の access は、モデルを ref できる範囲を制御するプロパティで、設計段階の一貫性と変更の安全性を高めます。特にレイヤード・アーキテクチャ（staging / intermediate / marts）と組み合わせると、依存関係の境界が明確になり、拡張時の影響評価が容易になります。

本稿では public / protected / private の基本、よくある設計パターン、YAML 実装例、CI での検証ポイントをまとめます。dbt Analytics Engineer 認定の出題傾向（モデルの境界、contracts・versions との併用、grants との違い）にも触れます。

access の基本と使い分け

access は主にモデルで利用するリソースプロパティで、他のパッケージやプロジェクトからの ref 対象にできるかを制御します。dbt はコンパイル時に access 違反を検出し、意図しない参照をブロックします。

基本的な方針は、staging は private、統合・中間層は protected、消費者向けのマートは public です。これにより、変更の影響半径を段階的に抑えられます。

• private: もっとも閉じた範囲。原材料データや不安定な中間形を保護
• protected: プロジェクト内や定義した境界内のみで共有。過度な公開を抑止
• public: 外部パッケージからの参照も許可。API 的な安定インターフェース

レイヤード設計パターン（stg / int / mart）

もっとも実務で安定するのは、レイヤごとに access を固定するやり方です。これにより、意図しない逆参照やスキップ参照（stg → mart の直参照など）を抑止できます。

別パッケージからは mart の public のみを参照可能とし、int（protected）は境界外から触れない前提にします。

• stg_*: private（ソース形状変動・命名揺れに耐える）
• int_*: protected（集約・正規化・キー付与などの中間）
• mart_*: public（キュレーション済み、契約とバージョンを明確化）

依存関係と公開境界（例）

実装例（YAML）と基本検証フロー

以下は、同一プロジェクト内でレイヤごとに access と group を付与した例です。contracts と versions を組み合わせ、public モデルの安定性を高めます。

access 違反は dbt のコンパイル〜ビルド時に検出されます。CI では依存パッケージを含めて dbt build を実行し、違反でジョブを失敗させます。

• group はドキュメンテーションや境界の意図表示に有用（命名を一貫）
• public には contract と version を併用し、互換破壊は新バージョンで提供
• CI で依存含め build し、access 違反を早期検出

models/schema.yml（例）

version: 2
models:
  - name: stg_orders
    description: Raw orders from source, lightly cleaned
    config:
      access: private
      group: staging
      contract:
        enforced: true
    columns:
      - name: order_id
        data_type: int
      - name: order_ts
        data_type: timestamp

  - name: int_orders
    description: Conformed orders, with keys and normalized types
    config:
      access: protected
      group: integration
    columns:
      - name: order_id
        tests: [not_null]

  - name: dim_customers
    description: Curated customer dimension (public interface)
    config:
      access: public
      group: marts
      contract:
        enforced: true
    versions:
      - v: 1
      - v: 2
    latest_version: 2
    columns:
      - name: customer_id
        data_type: int
      - name: customer_tier
        data_type: string

複数プロジェクト/パッケージ間の公開戦略

他パッケージから参照される前提のモデルは public に限定します。protected や private を外部から ref しようとすると、dbt はビルド前の段階で違反として検出します。

公開対象の変更時は、互換破壊と非互換を切り分けます。互換破壊は新しい version として提供し、latest_version を切り替えるまでの併走期間を設ける運用が安全です。

• 外部公開=public。非公開=protected/private
• 破壊的変更=新バージョン、非破壊=同バージョンで列追加（contractに注意）
• 依存側の更新タイミングを吸収するため、旧版の寿命を明示的に管理

access と他機能の関係（contracts・versions・grants）

access は「dbt 内の参照可否」を制御します。データベースの読み取り権限は grants（アダプタ実装）で別管理です。public でも、倉庫側の権限が無ければ直接 SQL では読めません。

contracts はスキーマ整合性、versions はインターフェースの時間的互換性を担保します。public モデルでは3点セット（access+contract+version）が実運用・試験双方での模範解答に近いです。

• access: dbt の ref ガード（設計上の境界）
• grants: 倉庫上の実権限。BI/外部ツールへの露出に影響
• contracts/versions: 公開 API の互換性を管理（列・型・進化）

試験対策と落とし穴

Analytics Engineer 認定では、層ごとの公開範囲、access・contracts・versions の組み合わせ、grants との違いが頻出です。シナリオ文から「誰が使うか」「どこまで公開するか」を判断してください。

protected と private の違いを混同しないこと、public を安易に増やさないこと、破壊的変更時は versioning を使うことが要点です。

• レイヤ別のデフォルト: stg=private / int=protected / mart=public
• public には contract と version を添える（互換性を設計）
• access は ref 可否、grants は倉庫権限という役割分担を明確に

問題で確認

よくある質問