Skip to content

Keep the definition

4

The change

Keep the definition

A filled decision and a filled comparison can still go stale the next time the query changes. This page is what I leave in place: who owns the definition, the columns the number promises, and the stop when those columns break.

My operating rule: name the owner of the published definition, check its columns before the next build, and stop the old number when those columns break.

Checked 16 Oct 2026

What I leave in place

This is the sheet I leave after Name the decision and When two reports don't match are filled. A blank field means the number is not being kept. The columns are dbt's model contract: the list of columns the published table promises, each with a name and a data type. dbt is the tool that builds the tables. When that list breaks, the build raises a contract error, and that error is the stop. The owner is my rule, and it is the approval the analytics field card requires. A change to the sentence of what one row means goes back to Say what one row means. A second report that will not sit on that row goes back to When two reports don't match.

Owner

The role that approves a change to the published definition. One person, or one role. A mailing list is not the owner. The field is filled when that role can say what one row means. Otherwise the number is not being kept.

Columns

Every column the number promises, by name and data type, with the contract turned on. The build checks that the query returns that shape. If it does not, the table does not build. What one row means stays on the other sheet. This field is the columns.

Break

A removed column, a changed data type, or a removed or changed constraint on a column the number already promised. That is a breaking change, and the build raises a contract error. The old number stops. Adding a column is not a break.

Version

When other people or systems depend on the table, the breaking change is a new version, and the previous version stays for a while so they can move. When nothing outside this team depends on it, the break can land at once. The field is filled when one of those two is named.

Reopen

A change to the sentence of what one row means goes back to Say what one row means. A second report that will not sit on that row, with the column names and types left alone, goes back to When two reports don't match. A change to the decision goes back to Name the decision. A green contract does not close any of those.

What the columns do not catch

dbt's contract is a promise about the shape of a table that other people and processes query. When it is turned on, the build checks that the query returns every promised column, with the promised data type. The check does not care about column order. dbt recommends a contract for a public table that reports and other systems rely on. A data test is a different check. It runs on the rows after the table has built, and it can be set to warn. The contract fails the build when the shape does not match. I do not use a warning as a substitute for that failure.

A breaking change, in that contract, is removing a column, changing its data type, removing or changing a constraint on it, or removing the contracted table. dbt then shows a contract error. Versions are how the person who owns a table that other teams use can introduce that break: a new version, the latest pointer moved, and a window in which the old version can still be used. dbt says making every consumer take the break at once is reasonable while the table is still changing quickly, or when the group that depends on it is small. Versions do not remove the cost of keeping two shapes. They put a limit on it.

The contract does not know the grain. Kimball's declaration is what one row means, in business words. A query can keep every column name and type and still change which rows are included. dbt says fixing a bug in how a column is calculated is not a breaking change, and it does not need a new version. That fix can still change the definition. When it does, I send it back to Say what one row means. If a second report then disagrees, that comparison is When two reports don't match. A green contract is not that sheet.

The Green Book includes comparisons and reconciliations in ongoing monitoring, and it ties a detective control to a correction that happens in time. I use that as the reason a break stops the next number, rather than waiting for someone to notice that the figure changed. The standard does not describe a model contract. The stop on a broken shape is the contract's. The owner is my rule.

An example

This is an illustration. It is not a portfolio I measured, and it states no amount.

The overdue-balance number is the invoice row from the filled comparison. Accounts already written off are left out. The owner is the role that approved that row. The contract includes the column that marks that boundary. The decision is still whether to give more time to pay.

A change removes that column. The shape breaks. The build stops. The lit sheet is the number that was kept. The cracked sheet is the shape that no longer matches. The sheet in the tray is the next version, and it is not the number until the owner accepts it. No amount is written.

A second change leaves every column name and type in place, and starts treating written-off accounts as included. The contract can stay green. That change is a new sheet on When two reports don't match. This page does not pick a number between the two meanings. If the meeting changes the decision from giving more time to a call list, that change is the brief on Name the decision.

How I would know

I watch four things. I have no target times, and these definitions are not results I have collected. A green contract that hides a changed grain is not the practice.

An unowned number is a published measure whose definition has no named owner.

A shape break is a build that stopped because the contract did not match.

A quiet change is a green contract whose grain, or what it includes, changed, and the comparison sheet was not reopened.

A kept version is a breaking change that still offers the previous version while people move.

The rows below are written for the illustration on this page. Neither is a result I collected, and neither states an amount.

Shape break

The column that marked written-off accounts as left out is removed.

Measure

Overdue balance. No amount is written.

Owner

The role that approved the invoice row.

Action

Stop the build.

Outcome

The old number stops. The sheet in the tray is not the number yet.

Quiet change

The same title, with every column name and type left in place, and written-off accounts moved in. Action: reopen When two reports don't match. Outcome: the contract stayed green, and the new meaning was not published. No amount is written.

Where I do not use it

A table that is still changing, and a search that is not being offered as an answer, do not get a contract. dbt says turning this on while tables are still changing makes later changes harder.

Comparing two reports stays on When two reports don't match. This page does not publish a number between them.

The decision, the person who will act, and the moves stay on Name the decision.

A contract does not apply to a seed, a snapshot, a source, or a Python model. A data test can still run on those.

Adding a column is not a breaking change. I do not open a new version for it.

The calendar, the blast radius, and the cutover stay on the technology delivery field card. A slow backtest of probability of default or expected credit loss stays on the Bayesian optimisation card.