Data Contracts Without the Hype

There is no shortage of articles about pandas. Most of them cover the happy path. This one is about what happened after the happy path ended.

We had good intentions. We even had a document describing how data contracts should work. The trouble was that the document and the code had quietly gone their separate ways.

How we got here

The setup was ordinary: pandas at the edges, dbt doing most of the heavy lifting, and a handful of scripts nobody wanted to own. It worked well until usage roughly doubled over a single quarter.

When we finally measured, the numbers were worse than anyone guessed. Around 24% of the time spent on a typical change went into working around data contracts rather than building anything.

The fix

The key insight was to treat data contracts as part of the interface rather than an implementation detail. Once we did that, most of the other decisions followed naturally.

Here's a trimmed-down version of what we ended up with:

SELECT
  user_id,
  event_at,
  LAG(event_at) OVER (PARTITION BY user_id ORDER BY event_at) AS previous_event_at
FROM events
WHERE event_at >= CURRENT_DATE - INTERVAL '30 days';

Nothing about this is clever, and that's the point. Anyone on the team can read it in a minute and know exactly what it does.

A few things that helped along the way:

• Write the migration guide before writing the migration.
• Pair on the first few changes so the knowledge doesn't live in one head.
• Keep the old path around until the new one has survived a real incident.
• Delete dead code aggressively; it's the cheapest refactor there is.

What it cost us

We still haven't solved data quality checks. That's a post for another day, and honestly, I'm not sure we'll get it right the first time either.

There are cases where this falls apart. If your team is very small or your traffic is very spiky, the extra moving parts may not pay for themselves.

What's next

If you take one thing away from this, let it be this: data contracts is a design decision, not a cleanup task. Make it early and make it on purpose.