Skip to main content

​
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

sqb --project-dir <path> compile [flags]

​
Flags

FlagDescription
--no-sql-validationSkip compile-time SQL syntax validation
--defer-toResolve unselected model references against another target
--jsonOutput the full compile report as JSON
--manifestGenerate target/manifest.json with project metadata
--lineage-modeColumn 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 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:
CodeMeaning
K001A declared column is missing from the model’s query output
K002A column’s inferred type does not match the declared type
K003A 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)

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

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:
ModeDescription
fastDefault. Lightweight column extraction using SQL model metadata.
richFull SQL analysis with transform classification and deeper tracing. Slower on large projects.
noneSkip column lineage entirely.
Column lineage results are included in the JSON compile report under each model’s lineage field. See Column Lineage for details on analysis modes and transform types.

​
Examples

# 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