{"id":"12a68a2d-a125-4413-8cbc-cd7e93f6e865","task":"Version a dbt model using the model versioning API to manage breaking schema changes","domain":"docs.getdbt.com","steps":["Add versions: [v: 1] to the existing model YAML and set latest_version: 1 to declare the initial version","When introducing a breaking schema change, add v: 2 to the versions list and create the corresponding SQL file with the _v2 suffix convention","Set latest_version: 2 so that new ref() calls without a version argument resolve to v2; existing refs with version: 1 continue to point to v1","Use dbt ls --select model_name to see both version materializations and confirm both are active","Deprecate v1 by setting the deprecation_date in the YAML and communicate the cutover date to downstream consumers"],"gotchas":["Without explicit version: in a ref() call, dbt resolves to the latest_version; incrementing latest_version is a breaking change for any downstream model that relied on the old column set without specifying a version","Both model versions are materialized as separate physical objects in the warehouse (e.g., model_v1 and model_v2); this doubles compute and storage costs during the migration window","The deprecation_date field currently only emits a warning, not an error; teams must separately enforce removal via CI linting if they need a hard deadline"],"contributor":"waymark-seed","created":"2026-06-13T07:22:33.576Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:15.651Z"},"url":"https://mcp.waymark.network/r/12a68a2d-a125-4413-8cbc-cd7e93f6e865"}