Bruin CLI 命令完全指南：用 `bruin run`、`bruin validate`、`bruin lineage` 与 `bruin query` 驱动你的数据流水线-港品优选

Bruin CLI 命令完全指南：用`bruin run`、`bruin validate`、`bruin lineage`与`bruin query`驱动你的数据流水线

【免费下载链接】data-engineering-zoomcampData Engineering Zoomcamp is a free 9-week course on building production-ready data pipelines. Join the course here 👇🏼项目地址: https://gitcode.com/GitHub_Trending/da/data-engineering-zoomcamp

导读

在 Data Engineering Zoomcamp 第 5 模块中，Bruin 被用作一个端到端数据平台：它把数据接入（ingestion）、转换（transformation）、编排（orchestration）、数据质量检查（quality checks）、元数据与血缘（metadata & lineage）整合进同一个工具。而命令（Commands）正是你与 Bruin 项目交互的入口——无论是执行流水线、校验配置、查看血缘，还是对连接执行即席查询，都通过 CLI 完成。读完本文，你将掌握bruin run、bruin validate、bruin lineage、bruin query四大核心命令的完整用法，理解"一次 run 是什么"，并能在纽约出租车（NYC Taxi）三层流水线上熟练实践。

为什么命令是 Bruin 的核心交互方式

命令是 Bruin 项目一切"动作"的载体。回顾模块 5 的核心概念体系：

Project（项目根目录）—— 通过bruin init初始化，.bruin.yml定义环境与连接（见 06-core-01-projects.md）；
Pipeline（流水线）—— 按调度分组的资产集合，pipeline.yml定义名称、调度、默认连接与变量（见 06-core-02-pipelines.md）；
Assets（资产）—— 具体执行工作的文件（Python 接入、SQL 转换、Seed 静态数据，见 06-core-03-assets.md）；
Commands—— 让一切"发生"：bruin run（执行）、bruin validate（校验）、bruin query（查询）。

简而言之：Project、Pipeline、Assets 描述"是什么"，Commands 决定"怎么做"。Bruin CLI 的安装方式为：

curl -LsSf https://getbruin.com/install/cli | sh bruin version

同时可以安装 VS Code / Cursor 扩展，获得 Bruin 渲染面板，直接在 IDE 内运行资产与流水线（详见 02-getting-started.md）。

`bruin run`—— 执行一条流水线

bruin run会为你的流水线创建一个单次执行实例（run）。最基本的用法是指定流水线定义文件的路径：

bruin run ./pipelines/nyc-taxi/pipeline.yml

运行作用域（Run Scope）选项

bruin run不仅可以运行整条流水线，还可以把执行范围精确收缩到某个资产：

选项	说明
整条流水线	按依赖顺序运行所有资产
单个资产	`--asset staging.trips_summary`
带上游	`--asset X --upstream`—— 运行 X 及其全部依赖
带下游	`--asset X --downstream`—— 运行 X 及其全部下游依赖

例如，只运行raw.trips以及依赖它的全部下游资产：

bruin run ./pipelines/nyc-taxi/pipeline.yml \ --asset raw.trips \ --downstream

作用域选项与资产的血缘（lineage）图紧密耦合：Bruin 根据资产间的读写关系自动构建依赖图，因此--upstream/--downstream能精确推导出需要一并执行的资产集合（资产依赖机制的详解见 06-core-03-assets.md）。

常用运行标志（Flags）

标志	说明
`--start-date DATE`	设置执行开始日期
`--end-date DATE`	设置执行结束日期
`--full-refresh`	删除并重建表（覆盖增量策略）
`--exclusive-end-date`	结束日期为开区间（默认为闭区间）
`--environment ENV`	使用指定环境（如 dev / prod）
`--var KEY=VALUE`	覆盖自定义变量

组合示例

# 简单运行 bruin run ./pipelines/nyc-taxi/pipeline.yml # 带日期范围运行 bruin run ./pipelines/nyc-taxi/pipeline.yml \ --start-date 2020-01-01 \ --end-date 2020-01-31 # 全量刷新并覆盖变量 bruin run ./pipelines/nyc-taxi/pipeline.yml \ --full-refresh \ --var taxi_types=["yellow","green"] \ --environment default

关键点：--start-date/--end-date会注入为内置变量，供资产内的 Jinja 模板（SQL）或环境变量（Python）读取，从而精确控制每个资产处理的时间窗口；--var则以KEY=VALUE的形式覆盖 pipeline 级自定义变量的默认值（变量机制的完整讲解见 06-core-04-variables.md）。在 NYC Taxi 示例中，--var taxi_types=["yellow","green"]会改变接入层抓取哪些出租车类型的数据（03-nyc-taxi-pipeline.md）。

`bruin validate`—— 运行前先校验

bruin validate在真正运行之前检查配置问题，是进入生产前的第一道安全网：

bruin validate ./pipelines/nyc-taxi/pipeline.yml

它会校验以下内容：

血缘图中不存在循环依赖；
资产定义是否正确；
连接（connection）是否存在且配置正确；
不存在断裂的引用。

实践建议：每次运行前务必先 validate！在 NYC Taxi 流水线中，标准做法是先校验再以小区间试跑（详见 03-nyc-taxi-pipeline.md）：

# 先校验结构与定义 bruin validate ./pipeline/pipeline.yml # 用小区间验证逻辑 bruin run ./pipeline/pipeline.yml --start-date 2022-01-01 --end-date 2022-02-01

对项目整体做校验也同样支持：bruin validate .（06-core-01-projects.md）。

`bruin lineage`—— 查看依赖图

bruin lineage用于可视化资产之间的连接关系：

bruin lineage ./pipelines/nyc-taxi/pipeline.yml

它展示资产间的上游（upstream）与下游（downstream）关系。结合 NYC Taxi 三层架构（接入 → 清洗 → 报表），血缘图会清晰呈现执行顺序：接入资产先并行运行（trips + lookup），staging 资产在两者完成后运行，报表资产最后运行（03-nyc-taxi-pipeline.md）。也可以只查看单个资产的血缘：

bruin lineage ./pipeline.yml --asset raw.trips_raw

`bruin query`—— 即席查询数据

bruin query对已配置的连接执行临时查询，适合运行后验证结果或做探索性分析：

bruin query --connection duckdb-default \ --query "SELECT * FROM ingestion.trips LIMIT 10"

在 NYC Taxi 示例中，接入完成后通常用如下命令确认数据落库：

bruin query --connection duckdb-default --query "SELECT COUNT(*) FROM ingestion.trips"

连接本身在项目级.bruin.yml中按环境定义（如 DuckDB、MotherDuck、PostgreSQL、BigQuery、Redshift、Snowflake 等），因此--connection指定的名称必须与该文件中对应环境下的连接名一致。

什么是"一次 Run"？

一次run是流水线执行的一个独立实例，具有以下特征：

拥有唯一的开始 / 结束时间；
可能运行全部资产，也可能只运行一个子集（通过--asset及作用域选项）；
携带自己的变量值（内置日期变量 +--var覆盖的自定义变量）；
产生执行日志与结果。

正因为每次 run 都是一次独立实例，你可以在不同时间点用不同参数反复运行同一条流水线（例如回填历史区间用--start-date 2020-01-01 --end-date 2020-01-31，增量更新用当前区间），而互不干扰。

把一切串起来：Bruin 完整工作流

1. Project (root, initialized) └── .bruin.yml (environments, connections) 2. Pipeline (scheduled grouping) └── pipeline.yml (schedule, default connection, variables) 3. Assets (the actual work) ├── Python (ingestion, processing) ├── SQL (transformations) └── YAML/Seed (static data) 4. Commands (make it happen) ├── bruin run (execute) ├── bruin validate (check) └── bruin query (inspect)

在一个典型开发循环中，你会：

用bruin init zoomcamp my-pipeline初始化项目（生成.bruin.yml、pipeline.yml、assets/骨架）；
在.bruin.yml中按环境配置连接（默认default环境，DuckDB 等），在pipeline.yml中配置名称、调度、start_date与默认连接；
编写资产（Python 接入、SQL 转换、Seed 静态表）；
bruin validate校验 —— 通过后再bruin run执行；
bruin lineage检查依赖是否正确；
bruin query验证结果数据。

快速参考

# 初始化新项目 bruin init zoomcamp my-pipeline # 运行前校验 bruin validate ./pipeline/pipeline.yml # 运行整条流水线 bruin run ./pipeline/pipeline.yml # 带日期范围运行 bruin run ./pipeline/pipeline.yml \ --start-date 2020-01-01 \ --end-date 2020-01-31 # 运行单个资产及其下游 bruin run ./pipeline/pipeline.yml \ --asset raw.trips \ --downstream # 全量刷新 bruin run ./pipeline/pipeline.yml --full-refresh # 覆盖变量 bruin run ./pipeline/pipeline.yml --var taxi_types=["green","fhv"] # 查看血缘 bruin lineage ./pipeline/pipeline.yml # 查询表数据 bruin query --connection duckdb-default \ --query "SELECT COUNT(*) FROM staging.trips"

企业官网建设流程全解析