Data Contracts Without the Hype

For a long time I treated data contracts as something to worry about later. Then a small change to our Airflow setup turned into a week of debugging, and "later" arrived all at once.

The setup was ordinary: Airflow at the edges, Snowflake 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.

What was going wrong

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.

Most of the complexity was accidental. Over the years we'd layered three different approaches to data contracts on top of each other, and each one made sense at the time.

A simpler approach

The fix turned out to be smaller than expected. Instead of adding another layer, we removed one and leaned on what Airflow already gives you out of the box.

Stripped of the project-specific bits, it looks like this:

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:

• Agree on what "done" means before the first pull request.
• 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.

What it cost us

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.

The biggest cost was social, not technical. Changing how people think about data contracts takes much longer than changing the code.

Closing thoughts

I don't think there's a universal answer here, but I hope this gives you a few ideas to try on your own project. If you do, I'd love to hear how it goes.