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.
This guide walks you through running the waffle shop example - a complete transformation project with views, tables, incremental models, audits, tests, and a custom materialization - all running locally against DuckDB. No external data setup required.
Prerequisites
- Python 3.12+
- SQLBuild installed:
uv add sqlbuild or pip install sqlbuild
1. Clone and set up
git clone https://github.com/chio-labs/sqlbuild.git
cd sqlbuild
uv sync
2. Plan
Preview what SQLBuild will do:
sqb --project-dir examples/waffle_shop plan
Plan ready (13 selected)
First run (12)
stg_customers view
stg_payments view
stg_orders view
daily_order_partitioned partition_tracked (custom)
daily_revenue table
dim_customers table
fact_orders table
customer_status_snapshot merge (timestamp)
hourly_order_activity delete_insert (timestamp, microbatch)
daily_activity_rollup delete_insert (timestamp, microbatch)
hourly_activity_with_daily_context delete_insert (timestamp, microbatch)
order_status_index delete_insert (integer)
Seeds (1)
waffle_types
sources/raw.yml, so SQLBuild resolves everything at compile time.
3. Build
Execute the full build:
sqb --project-dir examples/waffle_shop --no-color build
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
audit not_null (email) PASS
3/13 view stg_payments OK 0.02s
audit not_null (payment_id) PASS
audit unique (payment_id) PASS
audit not_null (order_id) PASS
4/13 view stg_orders OK 0.03s
test test_stg_orders PASS
audit not_null (order_id) PASS
audit unique (order_id) PASS
audit not_null (customer_id) PASS
audit accepted_values (status) PASS
5/13 custom daily_order_partitioned OK 0.17s
audit expression_is_true PASS 4/4
audit not_null (order_date) PASS 4/4
6/13 table daily_revenue OK 0.05s
audit expression_is_true PASS
7/13 table dim_customers OK 0.05s
audit not_null (customer_id) PASS
audit unique (customer_id) PASS
8/13 table fact_orders OK 0.04s
audit not_null (order_id) PASS
9/13 table customer_status_snapshot (merge) OK 0.04s
audit not_null (customer_id) PASS
audit unique (customer_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
11/13 table order_status_index (delete_insert) OK 0.03s
audit not_null (order_id) PASS
audit unique (order_id) PASS
12/13 table daily_activity_rollup (delete_insert) OK 0.08s
audit (d) expression_is_true PASS 2/2
audit (d) not_null (activity_day) PASS 2/2
audit (f) expression_is_true PASS
audit (f) not_null (activity_day) PASS
13/13 table hourly_activity_with_daily_context (delete_insert) OK 0.17s
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)
audit (d) and audit (f) on incremental models - these are delta-phase and final-phase audits. Delta audits validate each batch before DML is applied; final audits run against the target after promotion.
4. Verify
Run the plan again to see the steady-state:
sqb --project-dir examples/waffle_shop plan
Plan ready (13 selected)
Normal (12)
3 view
3 table
3 delete_insert (timestamp, microbatch)
1 partition_tracked (custom)
1 merge (timestamp)
1 delete_insert (integer)
Seeds (1)
waffle_types
Normal instead of First run.
5. Common operations
# Rebuild a specific model
sqb --project-dir examples/waffle_shop build --select daily_revenue
# Rebuild models under a path
sqb --project-dir examples/waffle_shop build --select path:marts
# Full refresh of everything
sqb --project-dir examples/waffle_shop build --full-refresh
# Run tests only
sqb --project-dir examples/waffle_shop test
# Run audits only
sqb --project-dir examples/waffle_shop audit
6. Project structure
examples/waffle_shop/
sqlbuild_project.yml # project config
sqlbuild_local.yml # local environment override
sources/
raw.yml # source declarations (inline expression data)
seeds/
waffle_types.csv # seed data
schema.yml # seed schema
models/
staging/
stg_customers.sql # view
stg_orders.sql # view
stg_payments.sql # view
schema.yml # audits for staging
marts/
fact_orders.sql # table
dim_customers.sql # table
daily_revenue.sql # table
daily_order_partitioned.sql # custom materialization
hourly_order_activity.sql # microbatch incremental
hourly_activity_with_daily_context.sql # microbatch incremental
daily_activity_rollup.sql # microbatch incremental
schema.yml # audits for marts
intermediate/
customer_status_snapshot.sql # merge incremental
order_status_index.sql # integer cursor incremental
schema.yml # audits for intermediate
audits/
generic/
not_null.sql
unique.sql
accepted_values.sql
expression_is_true.sql
tests/
test_stg_orders.sql # SQL unit test
materializations/
partition_tracked.py # custom materialization
Next steps
- Models - understand
MODEL() headers and materialization types
- Incremental - learn about cursor-based incremental strategies
- Audits - configure data quality checks
- Testing - write SQL unit tests with chaining and macro support
- CLI Reference - full command reference
