Handle source changes
When a warehouse table or a dbt model changes, the context built on it can break. Cassis shows what the change puts in doubt, so you update the context before answers go wrong.
When the warehouse changes
1. Read the plan
A plan lists what changed in the warehouse, and what that changes in the context. In this example, the warehouse gained a table and renamed a column.
In a git-managed project:
Check whether the warehouse schema changed and show me the Cassis plan.The warehouse changed: 2 schema changes, 1 context change.
| Schema diff | |
|---|---|
RETURNS | table added, not in the context |
ORDER_ITEMS.FREIGHT_VALUE | renamed to SHIPPING_FEE |
Context change: rename the column on ORDER_ITEMS, keeping its description.
Warnings: none. Apply it to the checkout?
Agent runs: cassis schema plan --warehouse
Agent: The warehouse changed: 2 schema changes, 1 context change. Schema diff: RETURNS, table added, not in the context; ORDER_ITEMS.FREIGHT_VALUE renamed to SHIPPING_FEE. Context change: rename the column on ORDER_ITEMS, keeping its description. Warnings: none. Apply it to the checkout?
Command: cassis schema plan --warehouse; for a project whose schema comes from an uploaded SQL file, pass the new file instead of --warehouse.
In an app-managed project:
Cassis checks connected warehouses nightly. On the Schema page, A plan is waiting opens the plan. Sync from warehouse makes one now; on a project whose schema comes from an uploaded SQL file, Update from DDL does the same with a new file.
| RETURNS | table added | Not in the context |
| ORDER_ITEMS.FREIGHT_VALUE | renamed | SHIPPING_FEE |
- Schema diff
- What changed in the warehouse. Here, a new
RETURNStable, andFREIGHT_VALUErenamed toSHIPPING_FEE. - Context changes
- What applying does to the context. Here, the rename carries over to
ORDER_ITEMS. A dropped column would also remove the joins and metrics that use it. - Warnings
- What the update would break, such as a metric whose column is going away. None here; read them whenever there are some.
2. Apply it
In a git-managed project:
Apply that plan to the checkout and show me the diff.Command: cassis schema apply --warehouse, which only edits local files. For a DDL project, pass the file path instead of --warehouse.
Then test and open a pull request as in steps 3 and 4 of the Git workflow.
In an app-managed project:
Choose Apply. It updates the stored schema and the unpublished context, without touching your warehouse or publishing anything.
Then review, test and publish as in steps 3 and 4 of the app workflow.
3. Add new tables yourself
A plan never adds a table to the context. RETURNS stays out until someone adds it and describes it; that is what the refund-rate issue in triage waits for.
In a git-managed project:
Add RETURNS to the Sales context and connect it to ORDERS. Ask me about missing business definitions and show me the draft for review.Commands: none from Cassis; the agent writes a file under cassis/tables/ in the tables format, then tests and opens a pull request as in the Git workflow.
In an app-managed project:
On the Schema page, find RETURNS, choose Add to context, and pick its domain. Describe it and its join to ORDERS, or hand it to the Assistant to model, then publish as in the app workflow.
When a dbt model changes
A renamed column or a dropped model in your dbt project can break the context before the warehouse even changes. Cassis catches it from the dbt project’s own CI, so setting it up and reading its findings do not depend on how your context is edited. Only the fix does.
Set it up once
Add two jobs to the dbt project’s CI (GitHub Actions and GitLab examples), then run cassis dbt push once on the production branch, so the first check has a baseline to compare with.
On every dbt pull request
cassis dbt check lists what the change puts in doubt, with the context change each needs. It files nothing and never fails your CI. Say a dbt pull request renames ORDER_STATUS on the orders model: the check lists the column and the two metrics that filter on it, revenue and active_customers, so the context fix can be ready before the dbt change merges.
After the merge, fix what it filed
cassis dbt push records the new baseline and files an issue for each part of the context still in doubt.
In a git-managed project:
List the Cassis issues filed by the last dbt change.3 open issues from dbt, all at_risk, from “Rename order status” (#412, a1b2c3d):
ORDERS.ORDER_STATUSis no longer built by dbtbusiness_volume(revenue) filters onORDERS.ORDER_STATUSactive_customersfilters onORDERS.ORDER_STATUS
All three are fixed by renaming the column in the context. Want me to do it on a branch?
Agent runs: list_issues (MCP)
Agent: 3 open issues from dbt, all at_risk, from "Rename order status" (#412, a1b2c3d): ORDERS.ORDER_STATUS is no longer built by dbt; business_volume (revenue) filters on ORDERS.ORDER_STATUS; active_customers filters on ORDERS.ORDER_STATUS. All three are fixed by renaming the column in the context. Want me to do it on a branch?
Then fix them as in the Git workflow.
In an app-managed project:
They appear in Review with the Possible dbt mismatch impact:
Then fix them as in the app workflow.