running-dbt-commands（运行 dbt 命令）

Running dbt Commands

Preferences

1. Use MCP tools if available (dbt_build, dbt_run, dbt_show, etc.) - they handle paths, timeouts, and formatting automatically
2. Always use build — even when users say "run" - When a user asks to "run" a model, recommend dbt build instead. build = run + test in one step, so it catches data quality issues immediately. dbt run alone is almost never the right answer during development.
3. Always use --quiet with --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' to reduce output while catching selector typos
4. Always use --select - never run the entire project without explicit user approval

Quick Reference

# Standard command pattern
dbt build --select my_model --quiet --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'

# Preview model output
dbt show --select my_model --limit 10

# Run inline SQL query
dbt show --inline "select * from {{ ref('orders') }}" --limit 5

# With variables (JSON format for multiple)
dbt build --select my_model --vars '{"key": "value"}'

# Full refresh for incremental models
dbt build --select my_model --full-refresh

# List resources before running
dbt list --select my_model+ --resource-type model

dbt CLI Flavors

Three CLIs exist. Ask the user which one if unsure.

Common setup: Core in venv + Fusion at ~/.local/bin. Running dbt uses Core. Use dbtf or ~/.local/bin/dbt for Fusion.

Selectors

Always provide a selector. Graph operators:

--select my_model              # Single model
--select staging.*             # Path pattern
--select fqn:*stg_*            # FQN pattern
--select model_a model_b       # Union (space)
--select tag:x,config.mat:y    # Intersection (comma)
--exclude my_model             # Exclude from selection

Resource type filter:

--resource-type model
--resource-type test --resource-type unit_test

Valid types: model, test, unit_test, snapshot, seed, source, exposure, metric, semantic_model, saved_query, analysis

List

Use dbt list to preview what will be selected before running. Helpful for validating complex selectors.

dbt list --select my_model+              # Preview selection
dbt list --select my_model+ --resource-type model  # Only models
dbt list --output json                   # JSON output
dbt list --select my_model --output json --output-keys unique_id name resource_type config

Available output keys for --output json: unique_id, name, resource_type, package_name, original_file_path, path, alias, description, columns, meta, tags, config, depends_on, patch_path, schema, database, relation_name, raw_code, compiled_code, language, docs, group, access, version, fqn, refs, sources, metrics

Show

Preview data with dbt show. Use --inline for arbitrary SQL queries.

dbt show --select my_model --limit 10
dbt show --inline "select * from {{ ref('orders') }} where status = 'pending'" --limit 5

Important: Use --limit flag, not SQL LIMIT clause.

Variables

Pass as STRING, not dict. No special characters (\, \n).

--vars 'my_var: value'                              # Single
--vars '{"k1": "v1", "k2": 42, "k3": true}'         # Multiple (JSON)

Analyzing Run Results

After a dbt command, check target/run_results.json for detailed execution info:

# Quick status check
cat target/run_results.json | jq '.results[] | {node: .unique_id, status: .status, time: .execution_time}'

# Find failures
cat target/run_results.json | jq '.results[] | select(.status != "success")'

Key fields:

• status: success, error, fail, skipped, warn
• execution_time: seconds spent executing
• compiled_code: rendered SQL
• adapter_response: database metadata (rows affected, bytes processed)

Defer (Skip Upstream Builds)

Reference production data instead of building upstream models:

dbt build --select my_model --defer --state prod-artifacts

Flags:

• --defer - enable deferral to state manifest
• --state <path> - path to manifest from previous run (e.g., production artifacts)
• --favor-state - prefer node definitions from state even if they exist locally

dbt build --select my_model --defer --state prod-artifacts --favor-state

Static Analysis (Fusion Only)

Override SQL analysis for models with dynamic SQL or unrecognized UDFs:

dbt run --static-analysis=off
dbt run --static-analysis=unsafe

Common Mistakes