Skip to main content

What you’re building

Models and sources keep changing: a column is renamed, a type widens, a table is added or a source is replaced. Updating a contract brings its draft in line with the current model without starting over. AI rewrites only the lines the change touches. Tables the change does not touch keep their check, and everything you changed yourself is kept. When you are happy, you approve again and the contract is saved as a new version. Earlier versions stay in Artifacts. This guide assumes you already have a contract. To make one, see Draft and approve a data contract.

Notice that something changed

On the model, the header Contract button shows a dot when its contract is out of date. Hover it to see Contract out of date: the model or its sources changed since version 1.0.0, using your last approved version. The check runs when you open the model, shortly after it saves, and about every half minute while the page is visible. Click Contract to review the change. While a contract is open, Snap Data Studio checks it against the model and its sources about every half minute. The same check runs when you open a contract after a change was made. When something differs, the status bar above the panels says so and offers Update contract, for example “TPCH sales changed since version 1.0.0”. These count as changes:
  • Tables or columns in the model added, removed, renamed or given a new type.
  • Source tables changed, added or removed.
  • A document you switched on for context changed.
  • The Instructions for AI, the project’s Agent instructions or your house rules (the contract defaults) changed.
If a source or document you selected has been deleted, the bar says it is no longer available and that the contract cannot be approved or updated until you replace it. Use the sources window described below.

Update the contract

  1. Click Update contract in the status bar. The bar reads Checking the model and its sources again. while it looks. While AI is still writing tables, it is unavailable and hovering it says why. Click Stop or wait for the run to finish. If nothing changed since the last check, a message says Nothing changed since the last check. and the contract stays as it was.
  2. Watch it work. The progress line in the left panel counts the changed tables, and only those tables show a stage under their name: Waiting, Finding sources, Writing or Checking. Activity on the right narrates each step as it happens, the same way it did for the first draft.
  3. Each changed table is ready to open as soon as it is done. Tables that need a look show it in their status, such as To check or Question for you.
Tables the change does not touch are not rewritten.

Change the sources or notes on purpose

You can also change what the contract is written from before updating.
  1. Click Overview in the left list, then open the ⋯ menu beside the contract name and choose Edit contract inputs.
  2. In Check the sources, click table chips to include or exclude sources, use Add source or the Add button under Reference documents, switch documents on or off, or edit Instructions for AI. Anything that has been deleted is marked No longer available.
  3. Click Update contract. You see Updating… while it runs. Cancel closes the window without changes.
Update contract needs at least one source selected.

Read what changed

After an update, What changed appears at the top of the Overview, above the tables. Its heading reads What changed since version 1.0.0 (the version you last approved), or What changed in this update if you have never approved. A one-line summary of how much changed sits under it. It then lists each change in plain words, for example:
  • Renamed column DIM_Customer.customer_id to customer_number.
  • FACT_SalesOrder.net_price changed type (NUMERIC(18,4), was NUMERIC(15,2)).
  • Added column FACT_SalesOrder.discount_pct.
  • Changed the Contract defaults.
The first five lines show. Click Show all 23 for the rest. If nothing relevant changed you see Nothing changed since version 1.0.0., and an approved contract stays approved. Open any table the update touched and its sheet starts with its own What changed, listing only the changes for that table. Lines AI rewrote are flagged like any line it was unsure about, so they are easy to find.

Migration notes

For tables that already hold data, a changed line can mean more than editing a definition. When a table loads incrementally or keeps every version of a row, Migration notes for the table opens a list of instructions for changing the existing table without losing rows or history. For example:
  • Rename the table from DIM_Cust to DIM_Customer in place. Keep its rows and history; do not create a new table and reload it.
  • Add column discount_pct (NUMERIC(18,2)) to the existing table without reloading it.
  • Stop loading column fax. Copy its values to a backup table before dropping it if anyone still needs them.
A table removed from the model gets a note that says not to drop it or its history as part of the change, and to retire it separately once nothing reads it. The notes are saved into the approved contract, next to each table, so the coding agent that builds from it knows how to move the existing data. They describe what to protect, not the exact commands.

Choose between your version and AI’s suggestion

A line you changed yourself is yours: an update will not rewrite it on its own. Usually it is carried over, and when a column was only renamed your line is updated to the new name for you. Asking AI to change a whole table also leaves facts written or accepted by people alone. Activity explains when that prevents a change. Click Go to Change beside the explanation to open the table and move to that fact’s Change button. When your line no longer fits the changed model, it is held back as a conflict. The table shows Needs your choice in the left list and in the Overview, and the status bar names the conflict and takes you to it. A conflict blocks Looks right on that table, which reads Choose a version for each line that changed., and so blocks approval. The conflict sits on the line it is about, whichever that is: Built from, One row is, Kept up to date, Changes over time, If a source row is deleted or a column. On that line, two panes sit side by side: Your version and AI’s suggestion. AI writes the suggestion for the changed model. While it works you see AI is writing a suggestion…. If none comes you see AI couldn’t write a suggestion. with the reason and Try again. Choose one:
  • Keep mine keeps your line exactly as you wrote it. It is available only if your line still fits the model. Otherwise it stays greyed out and you see Keep mine is unavailable. and every problem, for example Your version uses FACT_SalesOrder.line_number, which is no longer in the model or the selected sources. Click Edit to fix it yourself.
  • Edit opens the editor on your whole version of the line, so every part the change broke can be fixed in one Save. See Change a line.
  • Use AI’s suggestion replaces your line with AI’s suggestion.
When Kept up to date, Changes over time and If a source row is deleted belong to the same loading policy, every affected fact shows its own comparison. Each comparison says Applies to Kept up to date, Changes over time and If a source row is deleted. Choosing a version or saving your edits settles the whole policy, so those comparisons disappear together. Neither version is selected for you. Once you choose, the line drops out of the conflicts.

Check the changed tables and approve the new version

An update clears the check on every table it changed, so approval asks you to check those tables again.
  1. Open each table marked Updated, To check, Question for you or Needs your choice. An Updated table also says Updated under its summary, above What changed. Answer new questions, resolve conflicts and read the lines flagged AI wasn’t sure. The status bar’s Check next table button takes you to the next one.
  2. Click Looks right on each changed table. The status bar then reads, for example, “Ready to approve” with Approve contract.
  3. Click Approve contract. The window titled Approve and the contract name says which version it will save, for example This saves version 1.1.0 of the contract to Artifacts.
  4. Click Approve and save. While it saves, the button reads Saving version 1.1.0….
You see Saved version 1.1.0 to Artifacts. with Open. Version numbers follow what changed. A first approval is 1.0.0. Later approvals raise the middle number (1.1.0, 1.2.0). When a table or column was removed, a column’s type changed or what one row of a table stands for changed, the first number goes up instead (2.0.0), a signal to anyone who builds from the contract that the change is not backward compatible. If the saved contract file in Artifacts was edited by hand since the last approval, Before you approve warns you: Someone edited the saved contract file by hand. Approving keeps their edit as an earlier version.

Earlier versions

Updating never touches an approved contract. Until you approve again, the file in Artifacts is exactly what you approved last. Every approval adds a version named for the contract version, such as Contract 1.0.0 and Contract 1.1.0, and none is overwritten. To look back, open the contract file under contracts/ in Artifacts and click Versions in the header. Save and certify a version explains how to preview, certify and restore versions.

What’s next