# Create a Data Diff Check

Source: https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/

*Requires the Data Quality (DQ) module.*

Step-by-step tutorial for creating a Data Diff check between a target container and a reference container. For what each property means and how the rule evaluates the data, see the [How It Works](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/how-it-works/) page.

> **Note: Permission Required**
>
> You need the **Author** team permission on the datastore to create an Active check, or **Drafter** to create it as a Draft. See the [Permissions](https://userguide.qualytics.io/data-quality-checks/data-diff/deep-dive/permissions/) page for the full matrix.

> **Tip: Show me how**
>
> The app can walk you through this. Click **Show me how**  in the check creation form's header, or press `H` while it is open, and the **Add a Check** walkthrough highlights each step while you fill in the real form.

## Field reference

The **Authored Check Details** form is organized in the sections below. Fill them in as you follow the [Steps](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#steps).

### Target

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Associate with a Check Template** | No | Toggle | Links the check to a Check Template. Enabling it replaces the **Rule Type** dropdown with a **Template** dropdown where you pick an existing template, which then controls the check's properties. When off, you configure everything on this form. |
| **Rule Type** | Yes | Option | The validation logic to apply. Select **Data Diff** for this check. Shown only while **Associate with a Check Template** is off. |
| **Table / File** | Yes | Option | The target container the check runs against. Locked after the check is saved. |
| **Fields** | Yes | Option | The fields compared between the two sides, read on both the target and the reference container. Every field type is accepted. |
| **Filter Clause** | No | Text | A SQL `WHERE` expression that scopes the target container before the comparison. Keep it aligned with the reference filter so the two sides cover the same slice. |
| **Custom Anomaly Description** | No | Toggle | Has no effect on this rule. The option replaces the message on Record Anomalies, and Data Diff emits a Shape Anomaly only. |

> **Tip: Create the table or file from the form**
>
> If the table or file you need does not exist yet, click **Add Computed Table**  next to the **Table / File** field while it is empty (**Add Computed File** on a file-based datastore). Once saved, the new one is selected and pinned to the top of the list with a  icon until you close the form. The button appears only with the **Author** or **Editor** team permission on the datastore, and not when you add a check from Explore.

> **Note: A filter that can never run**
>
> **Validate** refuses a filter clause that can never convert a value, such as `amount <> ''` on a number field, or that uses a function Qualytics does not allow, and names the reason. This applies to every rule type that accepts a filter, including checks that compute one value for the whole table, such as **Sum**, and checks with a coverage below 100%. If a check with such a filter reaches a scan, it is reported as **Not Asserted** with that reason, and the other checks on the table still run.

### Properties

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Row Identifiers** | No | Option | The field (or combination of fields) used to pair each target row with its reference row. Strongly recommended: without identifiers the check reports a set-level difference and cannot classify rows or show them side by side. |
| **Passthrough Fields** | No | Option | Extra fields shown in the comparison view for context. They are displayed but never compared, so they cannot cause a difference. |
| **Diff Change Types** | No | Option | Which change types are reported: **added**, **removed**, **changed**. All three are selected by default. The field stays hidden until **Row Identifiers** holds at least one field, and clearing the identifiers clears the selection again, because classification depends on pairing rows. |

### Right Reference

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Datastore** | No | Option | The datastore holding the reference container. Leave it empty to use the target's own datastore. |
| **Container** | Yes | Option | The table or file compared against the target. |
| **Filter Clause** | No | SQL | A SQL `WHERE` expression that scopes the reference container before the comparison. Accepts Check Variables. |

### Comparators

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Numeric** | No | Toggle | Enables a tolerance for numeric fields, so values within the configured margin are not reported as different. Turning it on displays **Comparison** and **Threshold**. |
| **Comparison** | When Numeric is enabled | Option | How the tolerance is measured. **Absolute Value** uses a fixed margin; **Percentage Value** uses a percentage of the compared value. |
| **Threshold** | When Numeric is enabled | Number or Percentage | The allowed margin. The field is labeled **Percentage Threshold** when **Percentage Value** is selected. |
| **Duration** | No | Toggle | Enables a tolerance for date and timestamp fields. Turning it on displays **Unit** and **Value**. |
| **Unit** | When Duration is enabled | Option | The unit the tolerance is expressed in: **Millis**, **Seconds**, or **Days**. |
| **Value** | When Duration is enabled | Number | The allowed margin, in the selected **Unit**. |
| **String** | No | Toggle | Enables tolerant text comparison. Turning it on displays **Ignore Whitespace**. |
| **Ignore Whitespace** | No | Toggle | Ignores spacing differences between the two values. Shown only while **String** is enabled. |

### Ownership

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Owner** | Yes | Option | The user responsible for the check. Already filled in with the check creator. |
| **Anomaly Assignee** | No | Option | The user automatically assigned to anomalies the check produces. |

### Metadata

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| **Description** | Yes | Text | A plain-language description of what the check enforces. Supports Markdown formatting: click the field to open the Markdown editor. Click the **Apply suggested description**  button for a suggestion based on the rule type. |
| **Tags** | No | Option | Tags applied to the check for filtering and organization. |
| **Additional Metadata** | No | Key-value | Custom key-value pairs, typically links to catalog entries, tickets, or governance records. |

> **Info: No Pass Criteria section**
>
> Data Diff does not use coverage, so the form shows no **Coverage** slider. Any difference between the two sides that is not tolerated by a Comparator is reported.

> **Tip: Let AgentQ fill in the form**
>
> When [AgentQ](https://userguide.qualytics.io/agentq/getting-started/) is configured for your deployment, the **Check Assistant** panel in the check form can author the check for you: describe the comparison in plain language (for example, "the warehouse copy of orders must match the source system") and it proposes a configuration you can apply to the form. Review the filled-in fields, then Validate and Save as usual.

## Common Variations

| Goal | Fields | Row Identifiers | Diff Change Types |
| --- | --- | --- | --- |
| Validate a full replica against its source | every business field | the primary key | all three |
| Confirm a migration lost nothing | the migrated fields | the stable business key | **removed**, **changed** |
| Reconcile a daily delivery with the system of record | the delivered fields | the delivery line key | all three, with both filters scoped to the delivery date |
| Detect drift on a reporting copy, tolerating rounding | the metric fields | the report key | **changed**, with a numeric Comparator |

## Steps

Each field is described in the [Field reference](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#field-reference) above.

**Step 1**: Select the source datastore from the left menu, then click the **Checks** tab.

**Step 2**: Click **Add** in the top-right corner and select **Check** from the dropdown. The **Authored Check Details** form opens.

> **Warning: No tables available**
>
> On a datastore that has no tables yet, for example one that was just added and has not been synced, the form shows a **No tables available** warning (**No files available** on a file-based datastore) that reads **Run a Sync on this datastore before adding checks.** instead of the check fields. When you open the form from the datastore page and you can run operations on the datastore, the warning also offers a **Run Sync**  button, which closes the form and opens the Sync dialog. Add the check once the Sync finishes. The warning does not appear when you add a check from a check template.

**Step 3**: Select **Data Diff** in the **Rule Type** dropdown.

**Step 4**: Fill in the remaining [Target](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#target) fields: the target table or file, the **Fields** to compare, and, optionally, a **Filter Clause**.

**Step 5**: Under [Properties](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#properties), set the **Row Identifiers** that pair the two sides, add any **Passthrough Fields** for context, and restrict the **Diff Change Types** when only some change types matter.

**Step 6**: Fill in the [Right Reference](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#right-reference) panel: the reference **Container** (and its **Datastore** when it lives elsewhere) and an optional **Filter Clause** for that side.

**Step 7**: Optionally, set the [Comparators](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#comparators) so differences within a known tolerance are not reported.

**Step 8**: Fill in the [Ownership](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#ownership) and [Metadata](https://userguide.qualytics.io/data-quality-checks/data-diff/how-tos/create-a-check/#metadata) sections. Only the **Description** is required.

**Step 9**: Click **Validate** to test the rule against the selected data without saving it. A success message confirms the rule can run on that data. If validation fails, see [Troubleshooting](https://userguide.qualytics.io/data-quality-checks/data-diff/troubleshooting/#validation-fails-when-creating-the-check).

**Step 10**: Click **Save**. A success message confirms that the check was created.

*Last updated: November 10, 2026.*
