mcpField
R
running-dbt-commands

running-dbt-commands

github.com/dbt-labs数据与数据库7471.1k 次安装1 周前更新
代码仓库

关于 running-dbt-commands

面向数据从业者的 dbt 命令运行技能，涵盖模型选择、构建、预览和结果检查。它强调限定命令范围，并提供区分 dbt Core、dbt Fusion 与 dbt Cloud CLI 的指引。

主要功能

  1. 01开发时优先使用 dbt build
  2. 02要求明确指定模型选择器
  3. 03用 dbt list 预览选择结果
  4. 04用 dbt show 预览数据
  5. 05检查 run_results.json 中的结果
  6. 06区分三种 dbt CLI 的指引

适用场景

  1. 01构建选定模型并运行测试
  2. 02预览模型或内联 SQL 结果
  3. 03执行前检查选择器
  4. 04检查命令失败结果
  5. 05选择所需的 dbt CLI

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dbt-labs/dbt-agent-skills --skill running-dbt-commands

安装后在 Claude Code 中输入/running-dbt-commands确认已加载。

详细介绍

运行 dbt 命令

偏好设置

  1. 如果有 MCP 工具可用，请使用它们（dbt_build、dbt_run、dbt_show 等）——它们会自动处理路径、超时和格式
  2. 始终使用 build——即使用户说“run”也是如此——当用户要求“运行”模型时，建议改用 dbt build。build = run + test，一步完成，因此能立即发现数据质量问题。在开发期间，单独使用 dbt run 几乎从来不是正确选择。
  3. 始终使用 --quiet，并搭配 --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'，以减少输出，同时发现选择器中的拼写错误
  4. 始终使用 --select——未经用户明确批准，绝不运行整个项目

快速参考

# 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 版本

共有三种 CLI。不确定时，请询问用户使用哪一种。

版本位置说明
dbt CorePython venvpip show dbt-core 或 uv pip show dbt-core
dbt Fusion~/.local/bin/dbt 或 dbtf速度更快，SQL 理解能力更强
dbt Cloud CLI~/.local/bin/dbt基于 Go，在平台上运行

常见配置： venv 中安装 Core，~/.local/bin 中安装 Fusion。运行 dbt 会使用 Core。使用 dbtf 或 ~/.local/bin/dbt 运行 Fusion。

选择器

始终提供选择器。 图运算符：

运算符含义示例
model+模型及其所有下游节点stg_orders+
+model模型及其所有上游节点+dim_customers
+model+两个方向+orders+
model+N模型及其下游 N 层节点stg_orders+1
--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 model
--resource-type test --resource-type unit_test

有效类型：model、test、unit_test、snapshot、seed、source、exposure、metric、semantic_model、saved_query、analysis

Fusion： --resource-type 不支持与 dbt test 一起使用（dbt-fusion#1628）。在 Fusion 中运行单元测试：

  • dbt build --select model_name — 先构建模型，再运行所有测试（包括单元测试）
  • dbt build --select unit_test_name — 按名称指定单个单元测试
  • dbt list --resource-type unit_test — 列出可用于选择器的单元测试名称

列表

运行前使用 dbt list 预览将被选中的内容，有助于验证复杂选择器。

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

--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

展示

使用 dbt show 预览数据。使用 --inline 执行任意 SQL 查询。

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

**重要：**使用 --limit 标志，不要使用 SQL LIMIT 子句。

变量

以字符串形式传递，而不是字典。不要包含特殊字符（\、\n）。

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

分析运行结果

运行 dbt 命令后，查看 target/run_results.json 获取详细的执行信息：

# 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")'

关键字段：

  • status：success、error、fail、skipped、warn
  • execution_time：执行耗时（秒）
  • compiled_code：渲染后的 SQL
  • adapter_response：数据库元数据（受影响的行数、处理的字节数）

延迟（跳过上游构建）

引用生产数据，而不是构建上游模型：

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

标志：

  • --defer — 启用向状态清单的延迟
  • --state <path> — 指向先前运行生成的清单的路径（例如，生产环境构件）
  • --favor-state — 即使本地存在节点定义，也优先使用状态中的定义
dbt build --select my_model --defer --state prod-artifacts --favor-state

静态分析（仅 Fusion）

为包含动态 SQL 或无法识别 UDF 的模型覆盖 SQL 分析：

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

常见错误

错误修复方法
更改模型后运行 test使用 build——test 不会刷新模型
运行时未使用 --select始终指定要运行的内容
使用 --quiet 时未启用 warn-error添加 --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'
在虚拟环境中运行 dbt，却期望使用 Fusion使用 dbtf 或 ~/.local/bin/dbt
在 Fusion 中更改文件后出现架构错误运行 dbt clean 清除过期的架构缓存，然后重新运行
在 dbt_show 的 SQL 中添加 LIMIT改用 limit 参数
Vars 中包含特殊字符以普通字符串传递，不要使用 \ 或 \n

评论

支持 Markdown