Skip to main content

​
sqb build

Compiles, plans, and executes the build lifecycle. By default, only stale work runs; unchanged models, seeds, audits, and Python nodes are skipped automatically. Use --no-tests and --no-audits to skip validation for fast iteration.

​
Usage

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

​
Flags

FlagDescription
--forceOverride change detection and build all selected models regardless of state
--no-testsSkip SQL unit tests
--no-auditsSkip audits
--no-pythonSkip read-side Python tasks and assets (loader-side Python still runs for selected sources)
--no-sql-validationSkip compile-time SQL syntax validation
--full-refreshDrop and rebuild all selected models from scratch
--defer-toResolve unselected model references against another target
--defer-sources-toRead managed source data from another target
--fail-fastStop on first failure and skip remaining nodes
--concurrencyNumber of worker connections (default: 1)
--verbose, -vShow lifecycle SQL inline after each model
--start-cursor-tsOverride start cursor for timestamp incremental models (ISO format)
--end-cursor-tsOverride end cursor for timestamp incremental models (ISO format)
--start-cursor-intOverride start cursor for integer incremental models
--end-cursor-intOverride end cursor for integer incremental models
--loadExplicitly load managed sources before building
--no-loadSkip automatic source loading
--reloadReload managed sources (passes is_reload=True to loaders)
--include-stale-upstreamsExpand selection to include stale upstream models needed for coherence
--select, -sSelect specific models
--excludeExclude specific models

​
Fast iteration

Use --no-tests and --no-audits to skip validation when you only want to materialize models: 
sqb build --no-tests --no-audits
This replaces the former sqb run command. The full lifecycle (tests + audits) is always the default; skip flags opt out of specific phases when you need speed.

​
Execution order

  1. Managed sources are loaded (unless --no-load)
  2. Seeds are loaded (if changed)
  3. Source audits run before their dependent models (unless --no-audits)
  4. SQL unit tests run before their target model (unless --no-tests)
  5. Models are materialized in DAG topological order (unchanged models are skipped)
  6. Error-severity audits run against the staging table before promotion to the target (unless --no-audits)

​
Output

Execution  sqb build  (concurrency: 1)

   1/13  seed      waffle_types                                          OK     0.09s
   2/13  view      stg_customers                                         OK     0.05s
           audit     not_null (customer_id)                              PASS
           audit     unique (customer_id)                                PASS
   3/13  view      stg_orders                                            OK     0.03s
           test      test_stg_orders                                     PASS
           audit     not_null (order_id)                                 PASS
           audit     unique (order_id)                                   PASS
  10/13  table     hourly_order_activity  (delete_insert)                OK     0.16s
           audit (d) expression_is_true                                  PASS  4/4
           audit (d) not_null (activity_hour)                            PASS  4/4
           audit (f) expression_is_true                                  PASS
           audit (f) not_null (activity_hour)                            PASS

Completed successfully.
PASS=66  WARN=0  FAIL=0  SKIP=0  TOTAL=66  (1.09s)

​
Deferred builds

Use --defer-to to resolve unselected model references against another target. This lets you build a subset of models in dev while referencing production tables for everything else: 
sqb build --select fact_orders --defer-to prod
No manifest.json is required. Deferred references resolve directly against the live target.

​
Failure behavior

When a model fails:
  • Downstream models are automatically blocked and skipped
  • Staging/delta tables are retained for inspection
  • Failure details show the model name, failed phase, and error message

​
Fingerprints

After a successful build, SQLBuild writes version identities to _sqlbuild_fingerprints in the target schema. These are used on subsequent runs to detect changes and skip unchanged work. See Planning and Change Detection for details.

​
Runtime artifacts

Build writes executed lifecycle SQL to target/run/models/. These files contain the actual SQL that was executed, including resolved cursor bounds and runtime substitutions.