Skip to main content

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.

Virtual builds create versioned physical relations and update VDE pointer sets. The build lifecycle is the same as direct mode (seeds, tests, models, audits), but model outputs are written to versioned physical tables and exposed through logical VDE views.

​
Default VDE

When you run sqb build in virtual mode without --virtual-env, the VDE name defaults to the active physical environment name: 
sqb build
If the active environment is dev, this builds into VDE dev. On first run, it creates physical version relations and logical VDE views for all models.

​
Explicit VDE

Use --virtual-env to build into a named VDE: 
sqb build --virtual-env pr_123
If VDE pr_123 does not exist, SQLBuild creates it by inheriting refs from the baseline VDE (the default VDE for the active physical environment). Unchanged models share the same physical relations as the baseline - no data is copied. Only models with changed code, config, or upstream versions get new physical version relations.

​
Physical naming

Physical version relations are stored in a dedicated schema: 
<base_schema>__sqb_physical.<model_name>__v_<hash>
For example: dev__sqb_physical.fact_orders__v_8f3a9c12 Logical VDE views are created in a VDE-suffixed schema: 
<base_schema>__<vde_name>.<model_name>
For example: dev__pr_123.fact_orders When unsuffixed_virtual_env is configured, the named VDE uses the base schema directly: 
dev.fact_orders

​
VDE status

StatusMeaning
finalizedAll models match their expected version hashes. The VDE is coherent and eligible for promotion.
activeSome models are stale (partial build or pending changes). The VDE is a work in progress.
detachedThe VDE has been detached via sqb state detach. Build, promote, and rollback are blocked.

​
Partial builds

Build a subset of models with --select: 
sqb build --virtual-env pr_123 --select fact_orders
Partial builds leave the VDE in active (working) status if downstream models remain stale. A follow-up sqb build --virtual-env pr_123 (without --select) builds the remaining stale models to finalize the VDE.

​
Stale upstream coherence

If a selected model has stale required upstream models, the build blocks by default: 
sqb build --virtual-env pr_123 --select fact_orders
# error: selected models have stale required upstreams: stg_orders
Use --include-stale-upstreams to add the minimal stale ancestor closure: 
sqb build --virtual-env pr_123 --select fact_orders --include-stale-upstreams

​
Changes only

Use --changes-only to narrow the selection to only models that are both selected and stale: 
sqb build --virtual-env pr_123 --select path:marts --changes-only
This intersects the user selection with the default stale-driven selection, useful when the stale cascade is large and you want to build a coherent subgraph without running unchanged models.

​
Stale detection

SQLBuild determines which models need rebuilding by comparing expected version hashes against bound version hashes in the VDE refs:
  1. Expected local hash - derived from the model’s query SQL and version-identity config
  2. Expected version hash - local hash propagated through upstream dependencies (upstream hash changes cascade downstream)
  3. Bound version hash - the hash currently stored in the VDE refs from the last successful build
A model is stale when bound != expected. Stale models whose own local hash changed are roots (query changed, config changed, function changed). Others are stale due to upstream changed.

​
Seeded incremental builds

When an incremental model’s version hash changes, SQLBuild seeds the new physical version from the prior physical version before running the incremental delta. This avoids full rebuilds of large incremental tables.
AdapterSeed strategy
SnowflakeZero-copy clone
BigQueryTable clone
DatabricksDeep clone
DuckDB, Postgres, SQL ServerCTAS copy
For append models with bounded replay (query_change_backfill bounded-7d), the seed copies only rows before the replay window cutoff. The incremental delta then appends the bounded range without duplicating rows.

​
Limitations

Custom materializations are not supported in virtual mode. Models using custom materializations must use direct mode. Custom materializations can write arbitrary relations and may not follow the VDE physical/virtual lifecycle rules that virtual mode relies on.

​
Functions

Functions are published into the logical VDE schema, not the physical layer. Each VDE has its own copy of function definitions. Function versions are tracked in state and participate in promotion and rollback.

​
Plan

Use sqb plan to preview what a virtual build would do without executing: 
sqb plan
sqb plan --virtual-env pr_123
sqb plan --select fact_orders
Virtual plan output shows:
  • Virtual environment name and status (finalized/working)
  • Stale root count and root set
  • Stale model count
  • Query diffs from prior bound versions
  • Remaining stale models after partial selection