The Mental Model
A trusted model needs more than correct SQL. Users need to know what it means, who owns it, how fresh it is, and what changes are allowed.
Documentation is the instruction label on the data. Freshness is the expiration date. A contract is the promise that the shape will not change silently.
Dataset reference: ecommerce tables and grain assumptions.
Separate valid data from fresh data
At 09:00 UTC, the newest source ingestion timestamp is 08:10. A daily model can pass every key test while still violating a 30-minute freshness objective.
| Contract | Example value | Failure action |
|---|---|---|
| Owner | Payments data team | Route alerts to the accountable team |
| Loaded timestamp | ingested_at in UTC | Investigate missing or invalid timestamps |
| Maximum source age | 30 minutes during the agreed service window | Warn consumers that the source is delayed |
| Serving model age | Latest successful model run | Check transformation lag separately |
Expected finding: source age is 50 minutes, exceeding the example objective by 20 minutes. Use ingestion time when measuring delivery delay; an old event can arrive on time in a backfill. Document maintenance windows and empty-source behavior so an alert has an actionable meaning.
Interactive Check
Question: A payments source stops updating at midnight but tests still pass. What kind of check is missing?
Reveal the answer
A freshness check is missing. The data can be structurally valid but stale.
Practice: Write the Model Contract Card
Document one model with grain, owner, freshness expectation, and important columns.
Use the guided lab below to record your result, assumptions, and the check that would catch an incorrect result.