Problem
A source field can keep the same name and type while its meaning, value range or row grain changes. Queries may continue running while dashboards, forecasts, audiences or agents answer a different question.
Why it matters
Gong's September 17 Data Cloud notice provides a concrete example: WEEK in forecast submission tables will support negative values for future-period submissions and multiple future submissions can create more records per fiscal period. The same migration discipline applies to semantic models, context layers and destination rules across the revenue stack.
1. Write the old and new contract
Describe the field as a business interface, not just a database column. Record the authoritative source, table or object, entity grain, data type, allowed values, null meaning, time basis, freshness expectation and the business questions it is permitted to answer. Then write the new behavior beside it and mark the effective date.
For Gong's WEEK example, the important differences are that negative integers can represent submissions made before a period begins and that more than one future-period submission may exist for the same fiscal period. A migration owner should be able to point to those changes in one short contract before anyone edits downstream SQL.
2. Inventory every consumer
Search transformation repositories, semantic models, warehouse views, BI queries, alert definitions, spreadsheets, reverse-ETL models, agent tools and documentation for the field name and source tables. Include indirect dependencies where another model renames the field. Record owner, business purpose and criticality for each consumer.
Classify the intended question. A current-period forecast dashboard may intentionally exclude negative values. A submission-timing analysis may need them. A future-period pipeline review may need the additional rows but a historical KPI may not be comparable. The classification prevents a global find-and-replace from turning one source change into several unintended metric changes.
3. Build boundary fixtures
Create representative test records at the old and new boundaries: a positive active-period value, zero if valid, more than one negative value, multiple submissions for one period, a null case and an entity that joins to several downstream records. Preserve the expected result for each consumer before the migration.
Run the current logic against the fixtures and record where it silently drops, multiplies or mis-buckets rows. Then run the proposed logic. A passing test should assert business output as well as technical success: row uniqueness, totals, inclusion rules, labels and the exact value shown to an operator or agent.
4. Protect historical comparability
Ask whether the source provides equivalent historical evidence under the new semantics. If it does not, define an effective boundary and label metrics that mix periods with different coverage. Do not backfill meaning by applying today's rule to yesterday's absent data unless the source can reconstruct the underlying events.
For time-series reporting, decide whether to show a break in series, maintain separate versions or limit the metric to periods with comparable evidence. Store the metric version with exports and executive reporting so a future analyst can explain why two snapshots from different dates may not match.
5. Release in parallel
Keep the old and new derived views available during a bounded validation window. Run them over the same production snapshot and produce a difference table with record identifiers, old value, new value and reason. Review material differences with the business owner rather than asking engineering to decide what a revenue metric should mean.
Switch low-risk consumers first, then critical dashboards and agent contexts. For each release, capture the semantic version, query or model version, test result and activation time. If a destination or agent caches context, include cache invalidation or refresh behavior in the plan so old semantics do not survive after the source contract changes.
6. Roll back interpretation without deleting evidence
A rollback should restore the previous consumer behavior, not remove newly arrived source rows. Preserve raw data and move the semantic pointer, view or model back to the known version. This keeps the evidence available for diagnosis and prevents an emergency fix from destroying the records needed to understand the incident.
After rollback, identify whether the failure came from source semantics, grain, a join, a filter, visualization logic or an undocumented business assumption. Add that case to the permanent regression set before attempting the release again. The migration is complete only when the field contract, code and operating documentation agree.
Step-by-step workflow
- Name the field or metric owner and migration owner.
- Record the old contract, new contract and effective date.
- Search every direct and indirect consumer.
- Classify each consumer by business question and criticality.
- Build boundary fixtures for new values and changed row grain.
- Assert row uniqueness, totals, inclusion rules and operator-visible output.
- Document historical coverage and comparability limits.
- Run old and new logic in parallel on one production snapshot.
- Review differences with the business owner.
- Switch low-risk consumers before critical dashboards and agents.
- Capture semantic version, activation time and cache behavior.
- Keep a rollback that restores interpretation without deleting source evidence.
- Add incident cases to the permanent regression suite.
CRM fields and signals needed
- Source table or object, field name and semantic version
- Entity grain, primary key and relationship cardinality
- Allowed value domain, null meaning and time basis
- Direct and indirect consumer inventory
- Row-count, uniqueness and join-multiplication checks
- Historical coverage boundary and metric version
- Agent or activation consumers and cache freshness
- Release ID, approver, activation time and rollback result
Common mistakes
- Treating an unchanged column type as proof that the contract did not change.
- Fixing only the dashboard that first exposed the problem.
- Ignoring row-grain changes while testing only value parsing.
- Reinterpreting historical periods without equivalent source evidence.
- Letting engineering choose the business definition without the metric owner.
- Updating an agent prompt while leaving the governed model on old semantics.
- Deleting new source rows during rollback instead of restoring consumer interpretation.
Example operating rhythm
- At vendor change notice: open the dependency inventory and assign an owner.
- Before effective date: run boundary fixtures and parallel comparison.
- Release day: verify critical outputs and cached agent or activation context.
- First operating week: inspect difference logs and user-reported exceptions daily.
- Monthly: review high-consequence field contracts and unowned consumers.
Tooling options
- Use repository and warehouse lineage search to find direct and renamed dependencies.
- Use data tests for value domain, uniqueness, row grain and referential integrity.
- Use semantic or metrics-layer versioning where available.
- Use BI validation views to compare old and new results on the same snapshot.
- Use deployment records that connect source contract, model version, approval and rollback.
Source notes
These sources support the workflow model and product concepts. They do not prove a specific business outcome, benchmark result, or vendor claim.
- Gong Data Cloud change notice: Official September 17, 2026 notice documenting future-period forecast submission semantics.
- Fivetran + dbt Labs dbt Summit announcement: Official September 16, 2026 source for dbt v2, dbt State and Context Layer direction.
Last updated: 2026-09-18
Decision frameworks to read next
FAQ
Does every source-field change require a migration project?
No. The process should scale with consequence. A field used by one low-risk report may need a small test. A field used in forecasts, customer activation or agent actions needs a full dependency and rollback path.
Should negative values always be filtered out?
No. Their meaning is defined by the source contract and the business question. For Gong's future forecast submissions, negative WEEK values are meaningful evidence about submissions before a period begins.
Can we preserve one dashboard definition across the change?
Only if the old and new source coverage support the same business definition. If historical evidence is not comparable, keep an effective-date or version boundary visible.
What is the safest rollback?
Restore the prior semantic model, view or consumer logic while retaining raw source rows. Rollback should change interpretation, not destroy evidence.