running-dbt-commands

用途

该技能用于格式化并执行 dbt CLI 命令，选择正确的 dbt 可执行文件，并组织命令参数。适用于运行模型、测试、构建、编译等场景。

主要能力

优先使用 MCP 工具（dbt_build、dbt_run、dbt_show 等），它们会自动处理路径、超时和格式。
推荐使用 build 而非 run：当用户要求“run”某个模型时，建议改用 dbt build，因为 build = run + test，可立即发现数据质量问题；开发中单独使用 dbt run 几乎不是正确选择。
始终配合 --quiet 与 --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'，在减少输出的同时捕获选择器拼写错误。
始终使用 --select，未经用户明确批准不得运行整个项目。

使用方式

标准命令模式：

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

预览模型输出：

dbt show --select my_model --limit 10

运行内联 SQL 查询：

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

传入变量（多个变量用 JSON 格式）：

dbt build --select my_model --vars '{"key": "value"}'

增量模型全量刷新：

dbt build --select my_model --full-refresh

运行前列出资源：

dbt list --select my_model+ --resource-type model

dbt CLI 类型

存在三种 CLI，不确定时应询问用户：

类型	位置	说明
dbt Core	Python venv	`pip show dbt-core` 或 `uv pip show dbt-core`
dbt Fusion	`~/.local/bin/dbt` 或 `dbtf`	更快，SQL 理解能力更强
dbt Cloud CLI	`~/.local/bin/dbt`	基于 Go，在平台上运行

常见配置：Core 在 venv 中 + Fusion 位于 ~/.local/bin。运行 dbt 会使用 Core；使用 Fusion 需用 dbtf 或 ~/.local/bin/dbt。

选择器

始终提供选择器。图操作符：

操作符	含义	示例
`model+`	模型及所有下游	`stg_orders+`
`+model`	模型及所有上游	`+dim_customers`
`+model+`	双向	`+orders+`
`model+N`	模型及 N 层下游	`stg_orders+1`

--select my_model              # 单个模型
--select staging.*             # 路径模式
--select fqn:*stg_*            # FQN 模式
--select model_a model_b       # 并集（空格）
--select tag:x,config.mat:y    # 交集（逗号）
--exclude my_model             # 从选择中排除

资源类型过滤：

--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 — 列出单元测试名称以供选择器使用

List

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

dbt list --select my_model+ # 预览选择 dbt list --select my_model+ --resource-type model # 仅模型 dbt list --output json # JSON 输出 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

Show

使用 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' # 单个 --vars '{"k1": "v1", "k2": 42, "k3": true}' # 多个（JSON）

分析运行结果

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

快速状态检查

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

查找失败项

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

关键字段：

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

Defer（跳过上游构建）

引用生产数据而非构建上游模型：

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"]}'
在 venv 中却期望运行 Fusion	使用 dbtf 或 ~/.local/bin/dbt
Fusion 中更改文件后出现 schema 错误	运行 dbt clean 清除过期 schema 缓存，然后重新运行
在 dbt_show 的 SQL 中添加 LIMIT	改用 limit 参数
变量含特殊字符	以简单字符串传入，不要 \ 或 \n

适用场景

适用于需要执行 dbt 命令的开发与数据工程工作流，包括运行模型、测试、构建、编译、预览数据、分析运行结果等。

限制

三种 CLI 的行为存在差异，不确定时应询问用户。
Fusion 的 --resource-type 不支持与 dbt test 一起使用。
静态分析仅 Fusion 支持。
变量不支持特殊字符。
未经用户明确批准不得运行整个项目。