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

# compile

> Compile models into resolved SQL, validate contracts, and write target artifacts - fully offline.

# sqb compile

Compiles all discovered models, seeds, audits, and tests. Resolves references, expands macros, validates SQL, checks column contracts, computes column lineage, and writes compiled artifacts to `target/`. The compile command is fully offline - it does not connect to the warehouse.

## Usage

```bash theme={null}
sqb --project-dir <path> compile [flags]
```

## Flags

| Flag                  | Description                                                                    |
| --------------------- | ------------------------------------------------------------------------------ |
| `--no-sql-validation` | Skip compile-time SQL syntax validation                                        |
| `--defer-to`          | Resolve unselected model references against another target                     |
| `--json`              | Output the full compile report as JSON                                         |
| `--manifest`          | Generate `target/manifest.json` with project metadata                          |
| `--lineage-mode`      | Column lineage mode: `fast` (default), `rich` (slower, more detail), or `none` |

## What compile does

1. **Discovery** - finds `sqlbuild_project.toml`, scans for models, sources, seeds, functions, audits, tests, and macros
2. **Graph resolution** - resolves `ref()` and `source()` calls, expands macros, orders models by dependency
3. **SQL validation** - validates SQL syntax (when SQL analysis is enabled)
4. **Column lineage** - analyzes column-level dependencies across models (fast mode by default)
5. **Contract validation** - checks declared column contracts against inferred query output
6. **Artifact write** - writes compiled SQL to `target/compiled/`

## Static analysis

When SQL analysis is enabled (default), compile performs static analysis on your models without connecting to the warehouse:

* **Column inference**: Infers output columns from each model's SQL, including through CTEs, subqueries, and JOINs
* **Column contract validation**: If a model declares columns in its `MODEL()` header, compile checks that every declared column exists in the query output. If a column declares a type and `type_enforcement` is enabled, compile also verifies the inferred type matches the declared type
* **Column lineage**: Traces which source columns flow into each output column, including transform classification. See [Column Lineage](/concepts/column-lineage) for details

### Contract diagnostics

When a contract violation is found, compile reports it with source-annotated diagnostics:

```
error[K001]: required column 'total_cents' missing from model output
  model: fact_orders
  --> models/marts/fact_orders.sql:5:3
  5 | SELECT order_id, customer_id
    |        ^^^^^^^^
  = help: add total_cents to the SELECT list or remove it from MODEL(columns)
```

Diagnostic codes:

| Code   | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `K001` | A declared column is missing from the model's query output            |
| `K002` | A column's inferred type does not match the declared type             |
| `K003` | A column's type could not be proven (with `type_enforcement` enabled) |

Compile returns exit code `1` when any error-severity diagnostic is found, making it suitable for CI checks.

## Output

### Text output (default)

```bash theme={null}
sqb compile
```

```
Compile ready (12 models)

  stg_customers              OK  3 columns
  stg_orders                 OK  5 columns
  stg_payments               OK  4 columns
  fact_orders                OK  6 columns
  dim_customers              OK  4 columns
  daily_revenue              OK  3 columns
  ...

  Compiled: 12 models, 1 seed, 5 functions, 0 errors, 0 warnings
  Wrote: target/compiled/
```

Each model shows its name, status (OK or FAIL), and column count. Models with contract errors are marked FAIL.

### JSON output

```bash theme={null}
sqb compile --json
```

Returns a structured report including:

* `summary` - model, seed, function, audit, test, error, and warning counts
* `resources` - per-model details including column count, dependencies, lineage summary, and compiled SQL
* `diagnostics` - all contract violations with source locations
* `compile_timings` - timing breakdown for discovery, graph, lineage, contracts, and write phases
* `lineage_mode` - which lineage mode was used
* `artifacts` - paths to written files

## Column lineage modes

The `--lineage-mode` flag controls how column lineage is computed during compile:

| Mode   | Description                                                                                   |
| ------ | --------------------------------------------------------------------------------------------- |
| `fast` | Default. Lightweight column extraction using SQL model metadata.                              |
| `rich` | Full SQL analysis with transform classification and deeper tracing. Slower on large projects. |
| `none` | Skip column lineage entirely.                                                                 |

The JSON compile report includes a lineage summary for each model, not the full column graph. Use `sqb lineage <model>[.<column>]` to inspect lineage as a tree, edge list, or JSON. See [Column Lineage](/concepts/column-lineage) for details on analysis modes and transform types.

## Examples

```bash theme={null}
# Basic compile
sqb compile

# Compile with full JSON report
sqb compile --json

# Compile with rich column lineage
sqb compile --lineage-mode rich

# Skip column lineage
sqb compile --lineage-mode none

# Generate manifest
sqb compile --manifest

# Skip SQL validation
sqb compile --no-sql-validation
```