Module 8: Freshness, Contracts, and Documentation
Make data understandable, current, and safe to change.
95 minutes. 1 inline exercise. Free course module.
Learning Objectives
- Explain source freshness and data SLAs
- Document models and columns clearly
- Understand model contracts and ownership
Why This Matters
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.
Lesson Content
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.
Tiny Example
We will use a small ecommerce dataset throughout the course. Think of these as the only tables in your first warehouse:
| Table | Grain | Example columns |
|---|---|---|
raw_orders | one row per order event | order_id, customer_id, amount, status, created_at |
raw_order_items | one row per item inside an order | order_id, product_id, quantity, item_price |
raw_customers | one row per customer | customer_id, email, country, created_at |
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.
Inline Practice Lab
This lab is intentionally small. You can solve it by reading the table, writing the SQL/YAML mentally, or pasting the snippet into any SQL scratchpad later.
-- Example starter table
select
order_id,
customer_id,
amount,
status,
created_at
from raw_orders;The goal is not tooling setup. The goal is learning the production habit: state the grain, clean one thing, test one assumption, and explain the downstream impact.
Self-Check Quiz
- What is the grain of the table you are building?
- Which downstream metric or dashboard would be wrong if this model broke?
- What test would catch the most likely beginner mistake here?
Real-World Use Cases
- Reliable executive dashboards that do not disagree across teams
- AI analytics agents that query governed metrics instead of guessing SQL
- Auditable metric changes where owners can see downstream impact before merge
Production Notes
- A model without an owner has no one accountable when it breaks. Ownership is part of the data product.
Common Mistakes
- Writing descriptions that repeat the column name
- Ignoring freshness until executives report stale dashboards
- Changing column meaning without updating docs
Think Like an Engineer
- Can you explain the grain of this model in one sentence?
- What breaks downstream if this field becomes null tomorrow?
- Where should this logic live so it is reused instead of copied?
Career Relevance
Analytics engineering is the bridge between SQL skill and production data ownership. Freshers who learn tests, lineage, metrics, and semantic modeling early stand out because they can reason about trust, not just queries.
Key Terms
- Freshness
- How recently a source or model has received expected data.
- Contract
- A declared promise about model columns, types, and shape.
Inline Exercises
-
Write the Model Contract Card
Document one model with grain, owner, freshness expectation, and important columns.
30-45 minutes - Beginner to Intermediate
- Write the model description starting with "One row per..."
- Add owner and domain
- Add a freshness expectation for the source
- Mark columns that should not change type without review
Inline lab: complete the exercise directly in the course page.
Key Takeaways
- Freshness is a quality dimension
- Documentation prevents repeated tribal explanations
- Contracts make downstream breakage less likely