Migrate a breaking analytics schema change

WHAT THIS TESTS This checks whether you treat the event schema as a versioned contract with many consumers and plan an expand-then-contract migration rather than a risky rename.

A GOOD ANSWER COVERS Treat it as expand and contract. First expand: start emitting workspace_id alongside the existing project_id, dual-writing both for every event during a transition window, ideally with a documented mapping. Backfill: run a job that populates workspace_id on historical rows so time-range queries and trend dashboards do not show a discontinuity. Migrate consumers: update dashboards, alerts, experiment definitions, and pipelines to read workspace_id, one by one, verifying parity against the dual-written data. Contract: once nothing reads project_id, deprecate and remove it. Throughout, version the schema and announce timelines so teams can move.

COMMON WRONG ANSWERS A hard rename in one deploy, breaking everything reading the old key. Adding the new field but never backfilling, so historical charts break at the cutover date. Removing the old field before consumers migrate. No mapping, so old and new data cannot be reconciled.

LIKELY FOLLOW-UPS How do you detect stragglers still reading project_id before you drop it? How do you backfill billions of historical events efficiently? How do you keep an in-flight experiment valid across the change?

ONE CONCRETE EXAMPLE Week one, instrumentation emits both project_id and workspace_id with a one-to-one mapping. Week two, a backfill copies the mapped workspace_id onto all historical events. Weeks three to five, each dashboard and experiment is repointed to workspace_id and validated against the dual-written window. Week six, after confirming zero reads of project_id via query logs, the old field is deprecated and dropped.