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.

A model is a SQL file that defines one transformation step. Each model produces one table or view in the warehouse.

MODEL() header

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:
TemplateValue
${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

FieldDescription
materializedview, table, incremental, or a custom materialization name
tagsList of tags for selector filtering
schemaOverride target schema
databaseOverride target database
aliasOverride target relation name
pre_hookSQL statements to execute before materialization
post_hookSQL statements to execute after materialization
enabledSet to false to skip the model

Incremental config

FieldDescription
incremental_strategyappend, delete_insert, or merge
cursorOutput column used to track incremental position
cursor_typetimestamp or integer
cursor_grainTime grain for timestamp cursors: second, minute, hour, day, month, year
cursor_startLower bound floor for the cursor
cursor_inputsMap of upstream ref/source names to their cursor columns
unique_keyColumn(s) used for merge and delete_insert matching
incremental_modeSet to microbatch to enable batched execution
batch_sizeBatch window size (e.g. 1d, 1h, or an integer)
lookbackExtend the replay window backwards to re-process recent data
on_schema_changeappend_new_columns, sync_all_columns, ignore, or fail
query_change_backfillfull or bounded-14d (hyphenated duration)
schema_change_backfillPer-change-type backfill policies (e.g. add_column bounded-7d, type_change full)
See Incremental for detailed usage.

Custom materialization config

FieldDescription
configArbitrary key-value pairs passed to ctx.config in the Python function
placeholdersDefault values for @@placeholder tokens in the SQL

Diff config

FieldDescription
row_diff_exclude_columnsColumns to exclude from row-level diff comparisons
row_diff_tolerancesTolerance rules for numeric diff comparisons