dbt-versioning

Version dbt models by declaring a versions YAML block inside your model, mapping versions to distinct SQL files via defined_in, and using versioned ref() calls to ensure stable v1 and v2 compatibility. This allows downstream models to pin to a specific model version safely.

The latest_version setting determines which version a bare ref('model') resolves to, while allowing explicit ref('model', v=2) calls for pinning. This mechanism controls backward-compatible model evolution by directing default references to the designated version.

To create a v2 for an existing dbt model, enable the versions YAML configuration, add a new model_v2.sql file, and set latest_version to 2. Downstream models can then use ref('model_name') or explicit versioned refs to point to the desired version.

Yes, dbt model versioning enforces YAML versions configuration and file naming conventions to map versions to specific SQL files. Using the defined_in property within the versions block ensures dbt-core correctly resolves each version to its corresponding SQL file.

Yes, you can maintain stable v1 and v2 compatibility by leveraging the versions YAML block to define multiple model versions. Downstream models can independently pin to v1 or v2 using explicit ref() semantics, preventing breakages during model evolution.

A bare dbt ref() resolves to the version specified in the latest_version field of the YAML configuration. If it points to the wrong version, you need to check and update the latest_version setting or use an explicit ref('model', v=1) call to pin to the desired version.