kater compare

Compares two answers and shows where they differ, or compares an app's figures for two weeks.

Use --left and --right to check that a changed query, or a copy of a workspace, still returns the same rows. Each pair runs on the warehouse as one statement that returns only the rows that differ. Use --app and --periods to see how each figure of an app moved from one week to the next, and which figures stand out.

Examples

# Go to a connection in your local copy of Kater content
cd connections/snowflake_prod_connection
# Check that two saved queries return the same spend by platform and currency
kater compare --left workspaces/ad_reporting/query_contracts/spend_by_platform.sql --right workspaces/ad_reporting/query_contracts/spend_conversion_value_by_platform.sql
# Compare every query of the workspace with your brainstorm copy of it
kater compare --left workspaces/ad_reporting --right users/you@example.com/brainstorm/promote_roas/workspaces/ad_reporting
# Compare one query with your copy of it, over the last 6 complete months
kater compare --left workspaces/ad_reporting/query_contracts/paid_media_spend_trend.sql --right users/you@example.com/brainstorm/promote_roas/workspaces/ad_reporting/query_contracts/paid_media_spend_trend.sql --parameter is_within_last__union__date_day=6
# Compare the first two statements of a scratch file
kater compare --left users/you@example.com/brainstorm/promote_roas/spend_check.sql#0 --right users/you@example.com/brainstorm/promote_roas/spend_check.sql#1
# Compare an app's figures for the weeks of Sep 28 and Oct 5
kater compare --app app_129abe379bbf43b5a7012c252157e634 --periods 2026-09-28,2026-10-05

Options

Option	Description
`--left <side>`	The first side. Give a saved query by its file in a workspace’s `query_contracts/` folder. Give a scratch statement as its file, `#` and its number, counting from 0, such as `spend_check.sql#0`. Or give a workspace folder, whose queries pair by name with the other workspace’s.
`--right <side>`	The second side, given in the same way. A workspace pairs only with another workspace.
`--key <column>`	A column that pairs a row of one side with a row of the other, by the left side’s name. Without it, rows pair on the dimensions that both sides return. When there are none, Kater compares all the rows, in any order. You can give it more than one time.
`--column <left>=<right>`	Compares a left column with a right column that has another name. You can give it more than one time.
`--parameter <name>=<value>`	Sets a parameter on every side that declares it, and turns on the optional filters that read it. Kater reads the value as JSON, or else as text. You can give it more than one time.
`--precision <n>`	Compares numbers at this many decimal places, from 0 to 12, where that is finer than their format.
`--app <id>`	Compares an app’s figures for two weeks, in place of two sides: the app’s id, from the `id` in its `kater.app.yaml`. Give `--periods` with it. It takes none of the options above.
`--workspace <workspace>`	Compare a workspace’s figures for two periods: every query in it, by the workspace’s full path.
`--query <query>`	Compare one query’s figures for two periods: its workspace’s full path, then its name.
`--grain <grain>`	With `--app`, `--workspace` or `--query`: compare by hour, day, week, month, quarter or year. A week by default. Each workspace’s comparison date sets the grains it allows. It is `hour`, `day`, `week`, `month`, `quarter` or `year`.
`--periods <week>,<week>`	With `--app`: the two weeks, each by its Monday, such as `2026-09-28,2026-10-05`. The older week is the first, in either order.
`--refresh`	With `--app`: reads the app’s last weeks from the warehouse again before the check.

It also takes the global options --json, --kater-root, --scope and --help.

What each pair says

Verdict	What it means
`same`	Every compared row and column matches.
`different`	Some rows differ. It gives the first 50 differences. A difference is a value that differs, or a row that only one side has. It can also be a key that more than one row on one side has.
`only_left`, `only_right`	Across two workspaces, a query that only one of them has.
`refused`	A side could not run, and the message says why. For example, it does not compile, or you cannot read it. The other pairs still run.

The command prints each pair’s verdict and message, and its first 10 differences. The last line counts the pairs by verdict. --json gives every difference, and the first 10 rows that both sides have alike. A difference does not fail the command. It exits with 1 only when no pair differs and at least one pair is refused.

How it compares

Defaults apply. Each side runs with its own filters on and each parameter at its default, except the parameters that --parameter sets.
Columns pair by name, after --column gives a left column its right name. A column that only one side returns is listed, and not compared.
Numbers compare at the decimal places that their format shows. A number with no format must match to one part in a billion.
Paths that start with connections/ are from the content root. Other paths are relative to the folder you are in, or to --kater-root when you give it.

What it can compare

Queries compare from connection workspaces and from your own workspaces. A query in another person’s private workspace is refused.
Scratch statements run as kater show runs them.
One connection. Both sides must read the same connection. A side that compare does not run, such as custom SQL, is refused.
A copy and its original. Across a brainstorm copy and the workspace that it copies, changed marks each query that the copy changed. See Workspace copies.

An app’s figures

With --app, Kater compares each figure that the app’s page shows, at each row it shows, for the two weeks. It reads the weeks that Kater keeps for the app, not the warehouse, unless you give --refresh. Each figure gets these checks:

Change. How far the change between the two weeks is from the figure’s usual weekly change.
Value. How far the second week’s value is from the figure’s normal range over the weeks before.
Size. How much of the week’s total the move is, for a figure that adds up across rows.
Same week last year. The change from the same week one year before.
Decisions. Where the value is against each open decision on the app’s timeline that watches the figure.

The command prints the two weeks and how many figures stand out. Then come the figures that stand out, the strongest first, each with its two values, its change, the sentences of its checks and its series key. Then the other figures, one line each. A figure that moves with a figure above it is counted, and --json lists it. The last lines say when Kater checked the weeks and when it last read them from the warehouse.

When Kater has not checked the two weeks yet, the command starts the check and waits for it. It names the job, and while it waits it prints a line after 1 second and again every 10 seconds:

15:31:03  Kater has not checked these 2 weeks yet. Started the check (job 7f3a2c).
15:31:04  Waiting for the check (job 7f3a2c). 1s
15:31:14  Waiting for the check (job 7f3a2c). 11s

A check that reads stored weeks ends in seconds. A first read of an app’s weeks, or --refresh, waits on the warehouse. The command waits 15 minutes at most, then stops and the check keeps running: run the same command again to read it. Ctrl-C also leaves the check running, and the command exits with 130. A check that fails exits with 1 and says why. Only an app that you can read is checked.

Use the series key with kater figure trend to keep one figure’s weeks as an answer.

Through the MCP

Through the Kater MCP, the result’s app_url opens it in Kater. A copy and its original open on the copy’s compare view, at the query that the chat’s card opens on. Any other comparison opens at the left side’s place.