Model reference#

A model is one SQL file under models/. Its basename is the output table and its folder path supplies the output schema.

Leading directives#

Directives must appear in the leading comment header. The parser inspects at most the first 20 lines.

Directive	Meaning
`-- name:`	Explicit display name
`-- schema:`	Explicit output schema
`-- cadence: manual`	Exclude from recurring organization-wide runs
`-- depends_on: schema.table`	Add an explicit graph edge
`-- unique_key: column`	Upsert by this output column instead of replacing the table
`-- bigquery`	Route the statement to BigQuery; must be the first line and cannot reference `titan.*`
`-- query-<class>`	Pin the run to a larger memory class; use only when directed by a resource failure
`-- lint:`	Start a bounded typesql diagnostic-policy block

sql

-- schema: finance
-- cadence: manual
-- depends_on: stripe.charges
-- unique_key: customer_id
-- lint:
--   TS0609: allow

select
  customer as customer_id,
  sum(amount) / 100.0 as revenue
from titan.stripe.charges
where status = 'succeeded' and not _deleted
group by customer

Naming constraints#

A model cannot write into a schema owned by a connected source. Choose a derived schema such as finance or analytics. A basename change is an output-table rename.

Run states#

Steps record pending, running, succeeded, failed, or skipped outcomes. Manual models are skipped in recurring runs. A dependency failure prevents its downstream steps from starting.

Common failures#

A cycle or unknown explicit dependency refuses the graph.
A typesql error stops an enforce run and is recorded by stable code.
A missing unique-key column refuses upsert materialization.
A BigQuery-routed model that references titan.* is refused before submission.
A query timeout or exhausted memory budget fails the step without publishing a partial table.