> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqlbuild.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Column lineage

> Trace a column through your dbt and SQLBuild models, plus model-level lineage, from one command.

`sqb dbt lineage` traces dependencies across the combined dbt and SQLBuild graph:

* Point it at a **column** (`resource:column`) to trace where that column's values come from, or go, through every intermediate model.
* Point it at a **model** (no colon) for the model-level dependency graph.

It compiles the dbt project, reads the manifest, and analyzes the SQL, so lineage works whether a node is a dbt model or a SQLBuild model, and traces straight across the boundary between them.

## Column lineage

Target a column with `resource:column` (a colon between the model and the column):

```bash theme={null}
sqb dbt lineage agg_daily_revenue:revenue_cents
```

```
Column trace  agg_daily_revenue:revenue_cents  upstream

└── fct_orders:order_amount_cents (aggregation)
    └── int_order_payments:order_amount_cents (direct)
        └── stg_payments:amount_cents (aggregation)
            └── raw_payments:amount_cents (direct)
```

Each hop is annotated with how the value was derived (`direct`, `aggregation`, `expression`, ...), and the trace follows the column all the way back to the source - here through four models down to a seed. It also crosses the dbt/SQLBuild boundary: a SQLBuild column that reads a dbt model via `__dbt_ref` traces straight into the dbt model's columns. See [Column lineage](/concepts/column-lineage) for the full list of transform types and confidence levels.

Use `--direction downstream` to trace the other way - every column derived from this one:

```bash theme={null}
sqb dbt lineage stg_payments:amount_cents --direction downstream
```

```
Column trace  stg_payments:amount_cents  downstream

├── fct_payments:amount_cents (direct)
└── int_order_payments:order_amount_cents (aggregation)
    ├── fct_orders:order_amount_cents (direct)
    │   ├── agg_daily_revenue:avg_order_usd (aggregation)
    │   ├── agg_daily_revenue:revenue_cents (aggregation)
    │   └── agg_daily_revenue:revenue_usd (aggregation)
    ├── fct_orders:order_amount_usd (expression)
    └── int_customer_orders:lifetime_amount_cents (aggregation)
        ├── dim_customers:lifetime_amount_cents (expression)
        └── dim_customers:lifetime_amount_usd (expression)
```

Column lineage supports `--direction upstream` (default) or `downstream`, but not `both` - the same restriction as the native [`sqb lineage`](/concepts/column-lineage) command.

<Note>
  The dbt column target uses a colon (`model:column`); the native `sqb lineage` command uses a dot (`model.column`). The colon is used here because dbt model and package references already contain dots.
</Note>

## Model lineage

Target a model (no colon) for the model-level dependency graph:

```bash theme={null}
sqb dbt lineage fct_orders
```

```
Lineage  fct_orders [dbt]  upstream
└── int_order_payments [dbt]
    ├── stg_order_statuses [dbt]
    │   └── stg_orders [dbt]
    │       └── seed.jaffle_analytics.raw_orders [dbt]
    ├── stg_orders [dbt]
    │   └── seed.jaffle_analytics.raw_orders [dbt]
    └── stg_payments [dbt]
        └── seed.jaffle_analytics.raw_payments [dbt]
```

The `[dbt]` / `[sqb]` tag on each node shows whether it is a dbt or SQLBuild resource. `--direction both` shows upstream and downstream together:

```bash theme={null}
sqb dbt lineage fct_orders --direction both
```

```
Lineage  fct_orders [dbt]  both
upstream
└── int_order_payments [dbt]
    ├── stg_order_statuses [dbt]
    │   └── stg_orders [dbt]
    │       └── seed.jaffle_analytics.raw_orders [dbt]
    ├── stg_orders [dbt]
    │   └── seed.jaffle_analytics.raw_orders [dbt]
    └── stg_payments [dbt]
        └── seed.jaffle_analytics.raw_payments [dbt]
downstream
└── agg_daily_revenue [dbt]
```

## Options

| Flag                  | Description                                                                  |
| --------------------- | ---------------------------------------------------------------------------- |
| `--direction`         | `upstream` (default), `downstream`, or `both`. `both` is model lineage only. |
| `--depth`             | How many hops to traverse: an integer or `all` (default `all`).              |
| `--format`            | `tree` (default), `list` (an edge list of `a -> b` pairs), or `json`.        |
| `--no-sql-validation` | Skip SQL validation while compiling the SQLBuild side.                       |

The `list` and `json` formats keep fully-qualified resource names (e.g. `model.jaffle_analytics.fct_orders`) for unambiguous scripting; the `tree` format shortens them for readability.

See [Selection](/concepts/dbt-compatibility/selection) for how dbt and SQLBuild resources are named in the combined graph.