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.
A model is a SQL file that defines one transformation step. Each model produces one table or view in the warehouse.
Every model file starts with a MODEL() block that declares its materialization and configuration:
MODEL (
materialized table,
tags [marts],
);
SELECT
o.order_id,
o.customer_id,
w.waffle_name,
w.price_cents * o.quantity AS line_total_cents
FROM __ref("stg_orders") o
LEFT JOIN __ref("waffle_types") w ON o.waffle_type_id = w.waffle_type_id
Materialization types
view
Creates a database view. Rebuilt on every run.
MODEL (
materialized view,
tags [staging],
);
SELECT id AS order_id, customer_id, status
FROM __source("raw_orders")
table
Creates a table via CREATE TABLE AS. SQLBuild materializes into a staging table first, runs audits, then promotes to the target. Fully rebuilt each time.
MODEL (
materialized table,
tags [marts],
);
SELECT customer_id, COUNT(*) AS total_orders
FROM __ref("stg_orders")
GROUP BY customer_id
incremental
Inserts or updates into an existing table using a cursor-based strategy. See Incremental for full configuration.
MODEL (
materialized incremental,
incremental_strategy delete_insert,
cursor activity_hour,
cursor_type timestamp,
cursor_grain hour,
cursor_inputs (
fact_orders ordered_at,
),
incremental_mode microbatch,
batch_size 1d,
tags [marts],
);
SELECT
DATE_TRUNC('hour', o.ordered_at) AS activity_hour,
COUNT(*) AS orders_placed,
SUM(o.quantity) AS waffles_ordered
FROM __ref("fact_orders") o
GROUP BY DATE_TRUNC('hour', o.ordered_at)
custom
User-defined Python materialization function. Custom materializations get full access to the framework including adapter, schema change signals, query change detection, and audit hooks.
MODEL (
materialized partition_tracked,
tags [marts],
placeholders (
partition_start '\'2026-04-01\'',
partition_end '\'2026-04-05\'',
),
config (
tracking_table main.partition_state,
partition_column order_date,
date_range_start 2026-04-01,
date_range_end 2026-04-05,
),
);
SELECT
CAST(o.ordered_at AS DATE) AS order_date,
COUNT(DISTINCT o.order_id) AS order_count
FROM __ref("stg_orders") o
WHERE CAST(o.ordered_at AS DATE) >= CAST(@@partition_start AS DATE)
AND CAST(o.ordered_at AS DATE) < CAST(@@partition_end AS DATE)
GROUP BY CAST(o.ordered_at AS DATE)
Custom materializations use @@placeholder syntax for values substituted at runtime. The config block passes arbitrary key-value pairs to the Python materialize() function via ctx.config.
References
Models reference other models and seeds with __ref(), and sources with __source():
SELECT *
FROM __ref("stg_orders") o
LEFT JOIN __ref("stg_payments") p ON o.order_id = p.order_id
LEFT JOIN __ref("waffle_types") w ON o.waffle_type_id = w.waffle_type_id
SQLBuild resolves these references to qualified warehouse relation names during compilation.
DAG ordering
SQLBuild automatically discovers the dependency graph from __ref() and __source() calls, then executes models in topological order. Upstream models are always built before their downstream dependents.
Schema declarations
Models can have schema metadata declared in a companion schema.yml file in the same directory:
models:
- name: fact_orders
description: Order fact table with waffle and payment details.
type_enforcement: true
columns:
- name: order_id
type: INTEGER
audits:
- not_null
- unique
- name: customer_id
type: INTEGER
audits:
- not_null
audits:
- expression_is_true:
name: revenue is non-negative
expression: "total_revenue_cents >= 0"
Schema declarations support:
- Column-level audits: Attached to individual columns (e.g.
not_null, unique).
- Model-level audits: Attached to the model itself for multi-column or expression-based checks.
- Type enforcement: When
type_enforcement: true is set, SQLBuild casts columns to declared types and uses them for schema-change detection.
- Audit run scope: Audits on incremental models can specify
run_scope: delta_and_final to run on both the delta and the final target.
columns:
- name: activity_hour
audits:
- not_null:
run_scope: delta_and_final
audits:
- expression_is_true:
name: orders placed is non-negative
expression: "orders_placed >= 0"
run_scope: delta_and_final
Hooks
Pre-hooks and post-hooks execute SQL before and after materialization. They support macro expansion and context templates:
MODEL (
materialized table,
post_hook ['@grant_target(${CTX:target.qualified})'],
);
Available context templates:
| Template | Value |
|---|
${CTX:target.qualified} | Fully qualified target relation name |
${CTX:target.schema} | Target schema |
${CTX:target.name} | Target relation name |
${CTX:model_name} | Model name |
${CTX:environment} | Current environment name |
${CTX:run_id} | Current run ID |
Config reference
Common config
| Field | Description |
|---|
materialized | view, table, incremental, or a custom materialization name |
tags | List of tags for selector filtering |
schema | Override target schema |
database | Override target database |
alias | Override target relation name |
pre_hook | SQL statements to execute before materialization |
post_hook | SQL statements to execute after materialization |
enabled | Set to false to skip the model |
Incremental config
| Field | Description |
|---|
incremental_strategy | append, delete_insert, or merge |
cursor | Output column used to track incremental position |
cursor_type | timestamp or integer |
cursor_grain | Time grain for timestamp cursors: second, minute, hour, day, month, year |
cursor_start | Lower bound floor for the cursor |
cursor_inputs | Map of upstream ref/source names to their cursor columns |
unique_key | Column(s) used for merge and delete_insert matching |
incremental_mode | Set to microbatch to enable batched execution |
batch_size | Batch window size (e.g. 1d, 1h, or an integer) |
lookback | Extend the replay window backwards to re-process recent data |
on_schema_change | append_new_columns, sync_all_columns, ignore, or fail |
query_change_backfill | full or bounded-14d (hyphenated duration) |
schema_change_backfill | Per-change-type backfill policies (e.g. add_column bounded-7d, type_change full) |
See Incremental for detailed usage.
Custom materialization config
| Field | Description |
|---|
config | Arbitrary key-value pairs passed to ctx.config in the Python function |
placeholders | Default values for @@placeholder tokens in the SQL |
Diff config
| Field | Description |
|---|
row_diff_exclude_columns | Columns to exclude from row-level diff comparisons |
row_diff_tolerances | Tolerance rules for numeric diff comparisons |