dbt model contracts and versions

1.Contracts guarantee a model's shape

A model's columns usually come from whatever its select returns. That is convenient while you iterate, and risky once other people and processes query the model. A contract fixes the shape in advance. You declare the columns, their data types and, where the platform allows, their constraints. dbt then refuses to build the model if its SQL produces anything else. Contracts are recommended for public models that others rely on, whether inside dbt (other groups and projects) or outside it (dashboards and reports).

models:
  - name: dim_customers
    config:
      contract:
        enforced: true
    columns:
      - name: customer_id
        data_type: int
        constraints:
          - type: not_null
      - name: customer_name
        data_type: string

A contract is all or nothing. With enforced: true, every column needs a name and a data_type the platform understands. A partial contract is not allowed. For wide models that means a lot of YAML, and the explicitness is deliberate. At build time an enforced contract changes two things. First, a preflight check confirms the query returns matching column names and types, and column order doesn't matter to it. Second, dbt puts the names, types and constraints into the DDL it submits and orders the columns as the contract lists them, not as the SQL selects them.

Not every model can be contracted. SQL models materialized as table, view or incremental can, but each comes with a condition:

- Views support column names and data types, but not constraints. - Incremental models need on_schema_change: append_new_columns or fail. - Unsupported: Python models, materialized views, ephemeral models, custom materializations (unless the author added support), and BigQuery models with recursive CTEs.

Sources1

2.Constraints versus data tests

Declaring a constraint in a contract doesn't mean the platform will enforce it. dbt sorts every constraint, per platform, into one of three categories, and the category decides whether a violation actually stops the build. In cloud warehouses, many constraints can be declared but are not enforced. They are stored as metadata only.

Data tests are the more flexible tool. They run after the build against content you can query. They support custom severity thresholds, and their failures are easier to debug because the built model is there to inspect. Replacing a test with a constraint moves the validation to build time and probably costs less compute. It only works when three things are true: the platform enforces that constraint (most enforce only not_null), the model is a table or incremental, and the model has a full contract.

Tests are deliberately not part of the contract. Compare a software API: the structure of the response is the contract, while quality and uptime matter but sit outside it. Changing the structure in a backwards-incompatible way is a breaking change, and that is the point where versions come in.

Sources1

3.Breaking changes and when to version

With a contract enforced, dbt compares your project with its previous state and raises a contract error when it finds a change that could hurt downstream consumers. The changes it treats as breaking are:

- Removing an existing column. - Changing the data_type of an existing column. - Removing or modifying a constraint on an existing column (dbt v1.6 or higher). - Deleting, renaming or disabling a contracted model (dbt v1.9 or higher). This is an error for versioned models and a warning for unversioned ones.

A new version is for an intentional breaking change. Removing, renaming or retyping a column all qualify. Some changes pass the contract and still change what consumers see: different metric logic, a new grain, modified filters, a rewritten CASE statement. Whether those need a version is a judgment call for the model's owner. Small teams, and models that are still immature, can often just ship the break and have consumers adapt. That stops scaling once people and systems outside your control depend on the model.

Model versions work differently from git. Version control deploys one state of the whole project into an environment, and rolling back means reverting a commit. Model versions live side by side in the same repository and are deployed into the same environment at the same time, the way two or three versions of a web API run together. Each one you keep adds warehouse cost and clutter. Prefer non-breaking changes, and bump the latest version on a predictable cadence, once or twice a year and announced well in advance, rather than for every small change.

Sources123

4.Rolling out a new version safely

The riskiest part of releasing a new version is the default. A plain ref('model_name') with no version resolves to whatever latest_version points to. If latest_version isn't set, it is the numerically greatest version. So the moment you add v: 2, every unpinned consumer moves to it, breaking change included. To keep the default stable, give the new version its own SQL file (for example fishtown_analytics_orders_v2.sql), list both versions, and set latest_version to the old one until you're ready to switch.

models:
  - name: model_name
    latest_version: 2
    versions:
      - v: 3
      - v: 2
      - v: 1

Tools outside dbt never use ref. They query the table by name. An alias, or a view over the latest version, keeps an unsuffixed fishtown_analytics_orders object in the warehouse that always points at the current version, so BI dashboards keep working. A deprecation_date, supported since dbt 1.6, puts a known end on the migration window. Consumers can test the new version with ref('upstream_project', 'fishtown_analytics_orders', v=2). If it breaks them, they can pin to v=1 for now, but they still have to migrate before the deprecation date.

Sources342

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A contracted view enforces its not_null constraints the same way a table does.Why is that wrong?

   Views support contracts for column names and data types only. Constraints need a table or incremental materialization.

   Covered in Contracts guarantee a model's shape

2. 2.Adding v2 to a model's versions list leaves unpinned refs on v1 until you say otherwise.Why is that wrong?

   Without an explicit latest_version, unpinned refs resolve to the highest numerical version, so consumers move to v2 immediately.

   Covered in Rolling out a new version safely

3. 3.Data tests are part of a model's contract.Why is that wrong?

   The contract covers structure only: column names, types and constraints. Tests check content after the build.

   Covered in Constraints versus data tests