Getting started — your first reconciliation¶

Goal: from an empty tenant to a run that concludes pass_clean, with evidence you can inspect. Budget about 20 minutes.

This guide is deliberately concrete. If you are evaluating Paridity, doing this once teaches you more than reading the rest of the documentation.

Before you start¶

You need:

A role that can configure — platform_admin, tenant_admin, or operator. Auditors and analysts can see results but not create mappings.
Two systems to compare, and credentials for each stored in your secrets backend. Paridity never stores credentials; you give it a pointer.
Network reachability from the Paridity workers to both systems.
One table that exists on both sides. For a first run, pick the boring one: a modest row count, a single-column integer or string primary key, no BLOBs, and no rows changing while you test.

Most common first-run mistake: choosing a table that is actively being written. Paridity will correctly report a difference, and you will spend twenty minutes proving it was right. Start with something static.

The two paths¶

Open Setup → Onboarding Wizard (/onboarding). The first screen asks how you want to begin:

Choice	Use when
Start with tables	You know which tables you want compared. This is the normal evaluation path.
Start with a replication task	Your replication tool already defines the set of replicated tables, and you want Paridity to inherit that list. Requires a replication profile whose tool supports task discovery.

The rest of this guide follows Start with tables.

Step 1 — Systems (source and target)¶

Register the two systems you are comparing, or pick existing ones.

The important field is connection_ref, and it is worth understanding before you type anything: it is a URI pointer into your secrets backend, not a credential. Paridity resolves it at run time and never persists the secret.

aws-secrets://arn:aws:secretsmanager:us-east-1:123:secret/name
azure-keyvault://vault-name/secrets/secret-name
gcp-secretmanager://projects/proj/secrets/name/versions/latest
infisical://environment/path/SECRET_NAME
vault://secret/path/to/credential

Each system also declares a max concurrency, which acts as a hard ceiling: no mapping can ask that database for more parallel queries than you declared here, regardless of what the mapping says. See Systems and connections.

Use Test Connection before continuing. A failure here is far cheaper to diagnose than a failure three steps later.

Step 2 — Select tables¶

Paridity introspects the source and lists what it can see. Choose the table(s) you want compared.

System schemas (pg_catalog, information_schema, Oracle's SYS*, and so on) are hidden by default; there is a toggle to show them. For systems whose "schemas" are really user namespaces — Qlik spaces, object-store prefixes, folders — nothing is hidden, because those are your data.

Step 3 — Matches¶

Paridity proposes source→target pairs by name, using exact, case-insensitive, and prefix/suffix-stripped matching. Review these. Auto-matching is a convenience, not an authority — a wrong pair produces a confidently wrong comparison. Unmatched tables are listed so nothing disappears silently.

Step 4 — Configure¶

Field-level rules are inferred from column types: numeric scale from the column's scale, timestamp precision from its fractional digits, and BLOB/CLOB columns default to content-exact hashing.

For a first run, accept the defaults. When you later want to control comparison semantics per column, see Field configuration.

Step 5 — Preview¶

The proposals in full, before anything is created.

Paridity never auto-deploys a mapping. Auto-configuration produces proposals; a human confirms. This is deliberate — an incorrectly inferred key column silently changes what "matching" means.

Step 6 — Apply¶

Mappings are created in a single transaction: either all of them are created or none are. A partial batch would leave you guessing which half exists.

Step 7 — Schedule¶

Set how often the mapping runs. You can skip this for an evaluation and trigger runs manually.

Schedules are interval-based, not cron: an interval value and unit, optional days of the week, an optional daily time window, and optional calendar bounds. That shape exists because quarter-end and year-end scenarios are calendar-bounded, which cron expresses badly. See Schedules and close mode.

Run it¶

Go to Monitor → Runs (/runs) and trigger a run for your new mapping, or wait for the schedule.

What happens, in order¶

Readiness — if a replication profile is attached, Paridity checks the replication tool's state and the watermarks on both sides. If the target is still catching up, the run defers rather than comparing — this is the feature, not a delay.
Config audit — the resolved configuration is recorded with its checksum before any data is compared, so an auditor can prove which policy was in force.
Proof — row counts, then one aggregate fingerprint per side. If they match, the run concludes pass_clean and stops. No row data was moved.
Diff — only if proof failed: identify which rows differ (by per-row fingerprint), then which columns within them.

Reading the result¶

Status	Meaning
`pass_clean`	Source and target are identical for the compared window. This is the goal.
`no_new_data`	Nothing new since the last successful run — nothing to compare. Not a failure.
`fail_count`	Row counts differ. Usually missing or duplicated rows.
`fail_hash`	Counts match but the aggregate fingerprints differ — content differs somewhere.
`fail_field`	The diff phase identified specific columns that differ. This is the actionable one.
`pass_resolved_lag`	Initially mismatched rows resolved themselves on re-check - replication was simply behind, or one side had been read as of the readiness instant and both sides agree at latest.
`schema_drift_error`	A column changed in a way that halts comparison. Requires acknowledgement.
`system_error`	Something failed in the platform or a connector, not in your data.

The full vocabulary, including what to do about each, is in Runs.

If your first run fails¶

Work through these in order — the first three explain most first-run failures:

Is the table actively being written? Re-run against static data.
Is the window right? Without a watermark, Paridity compares a time window that may not mean what you expect on both sides. See Watermarks and windows.
Are the key columns correct? A wrong key makes unrelated rows look like mismatched pairs.
Open the evidence. fail_field tells you the exact column and both values. Frequently it is a type or precision difference — a timestamp stored at second precision on one side and microsecond on the other, or a numeric with different scale. Those are field configuration settings, not data defects.

What to look at next, as an evaluator¶

Trigger a deliberate failure. Change one value on the target and re-run. You should get fail_field naming that exact column, with both values shown (subject to your masking policy). That round trip is the product.
Look at the evidence trail. Evidence shows what an auditor would see, including the immutable comparison timestamp and the configuration checksum the run was pinned to.
Attach a replication profile and watch a run defer because the target is behind. See Replication profiles. This is the behaviour that distinguishes Paridity from a table-diff tool.
Read the configuration reference to see how much of the comparison you can control, and at which layer.