---
title: Model reference
description: Reference model file naming, leading directives, lint policy, states, and failure modes.
species: reference
---
# 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.