Only counts and checksums leave the database. By default a reconciliation retrieves row counts and aggregate checksums, never row values. Both sides can be in different databases, different clouds, or different accounts, and nothing is copied between them. Revealing more than that is opt-in, per reconciliation — see privacy levels.
When you need it
Monitors and tests tell you whether one dataset looks healthy. Reconciliation tells you whether two datasets tell the same story. Reach for it when correctness depends on a copy staying faithful to its origin:Migrations and replatforming
You are moving from one warehouse to another and need evidence — not a spot check — that the new platform returns the same data before you cut over.
Replica and CDC drift
A change-data-capture stream or read replica quietly falls behind, drops rows, or applies an update twice. Nothing in either system is “broken”, so nothing alerts.
Pipeline correctness
A transformation is supposed to preserve totals. Comparing the summary table against the operational source catches the day it stopped.
Source of truth vs warehouse
Finance reads the warehouse, the application writes Postgres. A reconciliation makes “the numbers don’t match” a measurable, scheduled check instead of an argument.
How a comparison runs
Every reconciliation runs in up to two stages, and the second one only happens if the first finds something.1
Compare — one query per side
A single aggregate query per database returns the row count and a checksum over the compared columns. It is fast and cheap no matter how large the tables are, and for the common case — the data agrees — this is the whole run.
2
Locate — bisect the key space
If the totals disagree, the drill-down splits the key range into segments and re-compares each one, recursing only into the segments that differ. Finding a handful of bad rows in a large, mostly-identical table takes a logarithmic number of queries rather than a full row-by-row diff.
Three stages, one suite
A suite is a YAML file holding one or more reconciliations plus the connections they use. The same suite moves through three stages, and the file never has to change to do it.
You can stop at any stage. A suite that only ever runs locally, reporting nothing to the cloud, is a supported way to use the tool — see standalone runs.
Where results show up
Once a suite is promoted, each reconciliation in it becomes a first-class part of your workspace rather than a line of terminal output:- Assets — every reconciliation in a deployment appears as an asset, so it shows up in search, lineage and folders alongside your tables and models.
- Checks — each run produces a check result, which means reconciliations participate in check categorisation and health reporting like any other check.
- Issues and incidents — a failing reconciliation opens an issue, with the mismatch detail attached.
- Alerts — issues route through your existing alert channels and ownership rules. There is no separate notification setup.
- Annotations — labels you put on a suite or reconciliation follow it into the platform and annotate the resulting assets and checks.
Where to go next
Getting started
Install, authenticate, and locate a real difference in a sample dataset.
Concepts
Suite, reconciliation, connection, deployment, run — the words used everywhere else.
Authoring suites
The YAML anatomy, choosing key columns, and the validation loop.
Agent workflow
The operating guide for a coding agent driving the CLI.