dbtのnode selection構文を実務と試験で使いこなす：tag / path / + / state:

dbt Core/Cloudの選択子（selector）は、対象ノードを最小限に絞り込み、速く安全にパイプラインを回すための中核機能です。

本稿では、試験でも問われやすく、実務でも多用される tag / path / +（model+の意） / state: を、誤解しがちなポイントとともに整理します。

セレクタ基礎と全体像

dbtのコマンド（run/build/test/seedなど）は --select と --exclude で対象ノードを指定します。選択方法は複数あり、代表例は tag:, path:, state:, リソース種別（model/test/seed/source など）、および系統展開の + です。ここでの + は「親（上流）/子（下流）の包含」を意味し、model+ という表現は my_model+（下流まで）や +my_model（上流まで）の総称としてよく言われます。

各セレクタは単独でも有用ですが、組み合わせることで CI の高速化、段階的リリース、夜間バッチなどを安全に実行できます。特に state: は過去のアーティファクト（manifest.json）と比較して差分だけを動かせるため、運用規模が大きいほど効果が出ます。

• 代表的な選択子: tag:, path:, state:, リソース種別（model:, test:, seed:, snapshot:, source: など）
• + の意味: +target は上流、target+ は下流、+target+ は上下流を包含
• state: 系は --state で参照先ディレクトリ（manifest.json のある target）を指定するのが前提

+（系統展開）の概念図

Upstream                 Target                 Downstream
   A  ---->  B  ---->  C  ---->  D
            ^
            |__ 選択対象: B

+B      =>  A, B         （Bとすべての上流）
B+      =>       B, C, D （Bとすべての下流）
+B+     =>  A, B, C, D   （上下流をすべて含む）

基本的な使い方（例）

### セレクタの基本
# タグで選択
 dbt build --select tag:nightly

# パスで選択（プロジェクトルートからの相対）
 dbt run --select path:models/marts/

# 系統展開（上下流）
 dbt build --select +dim_customers
 dbt build --select fact_orders+
 dbt build --select +stg_payments+

# state:（差分）
 dbt build --select state:modified+ --state path/to/previous/target --defer

tag: による論理グルーピング

tag: はモデルやスナップショット、シード、（必要なら）テストなどに付与して、論理的な束ねを実現します。物理パスに依存しないため、組織や運用ポリシーに沿った単位（nightly/heavy/finance など）で安全に回せます。

dbt build は、選択したモデルに依存するテストも自動的に実行します。テスト自体にタグを付けたい場合は、schema/properties YAML 側で tests 定義に tags を設定します。

• 命名ルールをチームで統一（例: 頻度、SLA、データドメイン）
• tag: は環境やクラスタ切替なしにサブセット実行が可能
• タギング忘れ検知のため、CIでセレクタカバレッジをチェックするのが有効

タグ付与と実行の例

-- models/marts/fact_orders.sql
{{ config(tags=["nightly", "heavy"]) }}
select ...

# schema.yml でテストにタグを付与する例
models:
  - name: fact_orders
    tests:
      - not_null:
          column_name: order_id
        tags: ["heavy"]

# タグでビルド
 dbt build --select tag:nightly

# 特定タグを除外
 dbt build --select tag:nightly --exclude tag:heavy

path: による物理配置ベースの選択

path: はプロジェクトルートからの相対パスでノードを指定します。ディレクトリを指すと配下のノードが対象になり、ファイルを指すと当該ノードのみが対象になります。モデル配置ポリシー（staging/marts など）が明確な場合にシンプルで強力です。

外部パッケージのノードを狙う場合、プロジェクトの packages/ 以下を指すか、package: セレクタの利用も検討してください。ファイル移動やリネームを行うと選択範囲が変わるため、レビューでの確認が有効です。

• ディレクトリ構造を整理できているほど有効
• 他パッケージの参照は package: も選択肢（用途に応じて使い分け）
• Windows でもスラッシュ表記（/）で統一しておくと混乱が少ない

path: の例

# ステージング配下のみ
 dbt run --select path:models/staging/

# 単一ファイルをピンポイント実行
 dbt run --select path:models/marts/fact_orders.sql

# 外部パッケージ（例: jaws_shop）配下（必要なら）
 dbt build --select path:packages/jaws_shop/models/

+（model+）で上下流を安全に含める

+ は選択範囲に上下流の系統を含めるための演算子です。+target は上流（parents）、target+ は下流（children）、+target+ は上下流の両方を含みます。ビルドやリファクタ時に取りこぼしを防ぐための必須テクニックです。

dbt build と組み合わせると、モデルに紐づくテストも適切に実行されます。影響範囲が広がり過ぎる場合は、--exclude と併用して調整します。

• 上流取り込み: +stg_payments
• 下流取り込み: fact_orders+
• 上下流取り込み: +dim_customers+
• 過大選択を防ぐ: --exclude tag:heavy などで制御

+ の活用例

# 影響する下流まで一気に検証
 dbt build --select stg_payments+

# 上流の前処理も含めて再計算
 dbt build --select +fact_orders

# 上下流すべて（大規模になる可能性があるので注意）
 dbt build --select +dim_customers+ --exclude tag:heavy

state: で差分だけを速く安全に回す

state: は過去のアーティファクト（通常は target/manifest.json）と現在のリポジトリ状態を比較し、変更（modified）や新規（new）になったノードだけを選択する仕組みです。--state で参照先ディレクトリを指定するのが前提です。運用では、本番ビルド成果を --state に渡し、--defer を併用して未変更部分を既存成果に委譲する使い方が定番です。

よく使うパターンは state:modified+（変更ノードとその下流）や state:new（新規ノードのみ）です。ファイル移動や名称変更、config の重要な差分（materialized など）も変更として扱われます。

• 前提: --state path/to/target（manifest.json が存在）
• --defer で未変更ノードの参照を既存成果に委譲（安全な差分ビルド）
• 変更検出はファイル移動・リネーム・一部config変更でもトリガーになり得る

state: の実例

# 変更ノードとその下流のみをビルド
 dbt build --select state:modified+ \
           --state s3://prod-artifacts/jaffle/target \
           --defer

# 新規ノードだけ検証（機能追加のスモークテストなど）
 dbt build --select state:new --state ./target-prod --defer

# 変更ノードのみテスト（モデルは既存成果に委譲）
 dbt test --select state:modified --state ./target-prod --defer

実務シナリオと試験向けの落とし穴

実務では、物理配置（path:）・論理（tag:）・系統（+）・差分（state:）を組み合わせて「最小で十分」な範囲を狙います。Analytics Engineer 試験でも、この発想とコマンドの正確さが問われます。

よくある落とし穴は、タグ付けの不統一、path: の移動影響見落とし、+ による広範囲選択、state: 利用時の --state/--defer 指定漏れです。安全側に倒すなら build と + を優先し、過大選択は --exclude で抑えます。

• 夜間バッチ: tag:nightly をベースに、重い処理は tag:heavy を除外
• 検証段階: path:models/staging/ に絞り、下流は staging+ のみ展開
• 本番差分: state:modified+ と --defer で速く安全に切替
• 移行期: + を使いつつ、--exclude path:models/legacy/ で段階的置換

組み合わせの例

# 夜間ジョブ（論理 + 除外）
 dbt build --select tag:nightly --exclude tag:heavy

# ステージング検証（物理 + 下流）
 dbt build --select path:models/staging/+

# 本番差分（state: + 下流 + defer）
 dbt build --select state:modified+ --state s3://prod/target --defer

# レガシーを除外しつつ影響範囲を検証
 dbt build --select +fact_orders --exclude path:models/legacy/

問題で確認

よくある質問