Skip to main content
This page defines the words that the other pages in this section use. If you read a run, an audit log or an API response and you do not know a term, look for it here.

​
The building blocks

A YAML file that holds one or more reconciliations and the connections they use. When you upload it, it becomes a stored, versioned object in your workspace. You save, version, run and promote a suite as one unit. A suite has a name, a title, and an optional description.
One comparison of one dataset with one other dataset. A suite contains reconciliations, each with a name under reconciliations:. A reconciliation passes or fails, becomes an asset when you promote the suite, and is what --include and --exclude select.
The two datasets of a reconciliation are the source (source:) and the target (target:). Each one is a side. The source is usually the origin of the data, and the target is the copy.
What one side reads: a connection and a table: or a query:. A table: dataset can be narrowed with columns:, exclude_columns: or where:.
The name that a dataset uses for the database it reads from. In a local run, a connection holds credentials. In a backend run, the same name binds to an integration. See connection vs integration. This difference causes more confusion than any other term on this page.
The column, or the tuple of columns, that identifies a row. You write it as key_column: or key_columns:, and both accept a string or a list. Key columns must be unique, and they should have an index. The drill-down sorts and filters on them, so an index keeps a drill-down cheap.
How the two sides are compared: row_count, row_checksum or aggregate. See Comparison modes.
The number of decimal places, or significant digits, at which row_checksum mode compares decimal and floating-point columns. The column types set a default, and comparison.numeric_scale changes it. See numeric precision.

​
Running and inspecting

Stage one of a run: the comparison of the reconciliation’s mode. In row_count and row_checksum modes, it is one aggregate query per side that returns counts, and checksums in row_checksum mode. It tells you if the two sides agree, but not where they differ. synq-recon run-check runs this stage only.
Stage two of a run: it narrows the difference step by step. In row_count and row_checksum modes, it splits the key range into segments. It goes further only into what did not match. synq-recon run-drill runs this stage, and synq-recon run --auto-drill runs both stages. With bisection.enabled: false, only run-drill and drill-deeper drill into a reconciliation. In aggregate mode, the quick check itself goes down the group_columns hierarchy.
A segment is a key range that the drill-down compared as one unit. A mismatch leaf is a segment where the two sides do not agree and the drill-down stopped. It stops at the row threshold, at the depth limit, or when the segment cannot be split. Leaves are the result you act on: each one has the key range, the reason the drill-down stopped, and SQL that returns the rows.
One execution of a suite. A run has a status, a trigger, timings, and a result for each reconciliation. Every run has an invocation id. You use it to get a stored run later.
A local run is a run that you start with synq-recon on your own machine. It uses the credentials in your connections file. A backend run is a run that Coalesce Quality executes with the integrations of your workspace: an ad-hoc run of a Development suite, a scheduled run, or a triggered run. A backend run never reads row values, so some settings work only in a local run.
The full record of a run: every query as it was executed, and every count, checksum, timing and mismatch leaf. A local run writes it with --audit-log <path>. The workspace stores it for backend runs, and for local runs that report their results. Its structure is published as the audit-log schema. It records connection names, never credentials.
Why a run started: adhoc (started on demand for a Development suite), scheduled (a schedule started it), or api (an explicit trigger: the Run button on a promoted suite, or an external caller such as a CI job).

​
Development, Production and deployments

The stage of a suite that you save to the workspace with upload-config, or create in the new-suite wizard of the app. It is stored and versioned, and you can run it on demand. It does not run on a schedule. It is the shared draft.
The stage of a suite after you promote it. Its results become platform assets and checks. It can run on a schedule, or when an API call triggers it.
What a promote makes: an immutable snapshot of the suite, with its schedule, connection bindings, run settings and annotations. A deployment is a snapshot, not a pointer. If you edit the suite in Development, Production does not change until you promote it again.
Each upload-config makes a new version of the stored suite, with an optional --change-summary. synq-recon suite versions <id> lists the versions, and the app has a version picker. A promote copies one version into the deployment.

​
Connection vs integration

The same YAML key has two meanings. The meaning depends on where the suite runs. Read this section carefully one time.
  • A connection is the name that a reconciliation uses. It is always only a name.
  • An integration is a database credential that your workspace manages, with a UUID. Backend runs use integrations. They never see the credentials in your YAML.
In a backend run, each connection name binds to an integration. By default, the name and the integration id must be equal: a connection named warehouse binds to the integration whose id is warehouse. To bind to a different integration, map it:
Keep credentials out of the suite. Put them in a git-ignored .connections.yaml with the same connection names. Then the same suite file runs locally with your credentials, and on the backend with integrations, and you change nothing between them. Authoring suites shows the layout.

​
Replaying a finished run

Runs the queries of a finished run again and reports what changed. It answers the question “did the difference go away?”, for example after a backfill, a pipeline fix or a redeploy. In the CLI, synq-recon recheck <run>. In the app, Re-check on the run detail page.
Continues the drill-down of a finished run from where it stopped, at a lower threshold or with one more group column. In the CLI, synq-recon drill-deeper <run>. In the app, Drill deeper.
Both run the queries that the audit log recorded again. They do not derive the queries again, so the question “did it change?” compares the same data. Investigating results gives the details.

​
You may also see

Older suites, stored YAML and API payloads sometimes use different names. All of them work. The left column is the name that the documentation uses.