# Create an Entity Resolution Check

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

*Requires the Data Quality (DQ) module.*

Step-by-step tutorial for creating an Entity Resolution check that clusters records describing the same entity and verifies they share one distinction value. For what each property means and how the rule scores and clusters records, see the [How It Works](https://userguide.qualytics.io/data-quality-checks/entity-resolution/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/entity-resolution/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/entity-resolution/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 **Entity Resolution** for this check. Shown only while **Associate with a Check Template** is off. |
| **Table / File** | Yes | Option | The container the check runs against. Locked after the check is saved. Entity Resolution has no **Field** picker: the evaluated fields come from the Block and Compare Fields below. |
| **Filter Clause** | No | Text | A SQL `WHERE` expression that limits the records entering resolution. Rows outside the filter cannot be clustered or reported. |
| **Custom Anomaly Description** | No | Toggle | Has no effect on this rule. The option replaces the message on Record Anomalies, and Entity Resolution 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 |
| --- | --- | --- | --- |
| **Distinction Field** | Yes | Option | The field that must be consistent inside each cluster. A cluster holding more than one value of this field is reported. Accepts `Date`, `Timestamp`, `Integral`, `Fractional`, `String`, and `Boolean` fields. |
| **Block and Compare Fields** | Yes | List | The fields that describe the entity. Click **Add target field**  to add an entry; while the list is empty, clicking the section title does the same. Each entry opens the controls listed under [Inside a Block and Compare Fields entry](https://userguide.qualytics.io/data-quality-checks/entity-resolution/how-tos/create-a-check/#inside-a-block-and-compare-fields-entry), shows the field type and role as chips in its header, and has a **Remove**  button. At least one entry is required. |
| **Composite Match Threshold** | Yes | Percentage | The weighted score two records must reach to land in the same cluster. Defaults to 70%. Raise it to cluster more conservatively, lower it to tolerate more variation. |

#### Inside a Block and Compare Fields entry

Each entry starts with the **Field** picker. The remaining controls appear once a field is chosen, and which ones appear depends on the field's data type and on the choices above them.

| Control | Shown for | Type | Description |
| --- | --- | --- | --- |
| **Field** | Every entry | Option | The source field this entry evaluates. The list offers every field of the selected table or file except the **Distinction Field**. The field's data type decides how it is compared: `Integral` and `Fractional` fields are handled as **Numeric**, `Date` and `Timestamp` as **Date / Time**, and every other type as **String**. |
| **Field Role** | Every entry | Option | **Compare** (default) contributes weighted evidence to the match score. **Block (advanced)** is a hard boundary: records with different values in this field are never paired. Choosing Block sets the comparison to **Exact Match** and hides the weight. |
| **Comparison Type** | Every entry | Option | How two values of the field are compared. String fields offer **Fuzzy Match** (default) and **Exact Match**. Numeric fields offer **Absolute (delta)** (default), **Relative (%)**, and **Exact Match**. Date / Time fields offer **Offset** (default), **Granularity**, and **Exact Match**. Block fields always use **Exact Match**. |
| **Weight** | Compare fields | Number | How much this field counts in the composite score. Defaults to `1`. The same number on every field means equal weighting; raise one to make it count more. |
| **Pair Substrings** | String, Fuzzy Match | Checkbox | Treats the values as a match when one is part of the other. On by default. |
| **Pair Homophones** | String, Fuzzy Match | Checkbox | Treats the values as a match when they sound alike, even if spelled differently. On by default. |
| **Prioritize rare matches** | String, Fuzzy Match | Checkbox | Gives a shared uncommon value more influence on the score than a shared common value. Off by default. |
| **Offset** | Numeric, Absolute or Relative | Number or Percentage | The tolerance within which two numbers count as equal: a fixed difference for **Absolute (delta)**, a percentage for **Relative (%)**. |
| **Offset (seconds)** | Date / Time, Offset | Number | The number of seconds within which two date or time values count as equal. |
| **Granularity** | Date / Time, Granularity | Option | The period two values must share to count as equal: **Day**, **Week**, **Month**, or **Year**. |

### 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**
>
> Entity Resolution does not use coverage, so the form shows no **Coverage** slider. The composite match threshold, not coverage, controls how tolerant the check is.

> **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 entity in plain language (for example, "customers with the same name and city should share one customer ID") and it proposes a configuration you can apply to the form. Review the filled-in fields, then Validate and Save as usual.

## Steps

**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 **Entity Resolution** in the **Rule Type** dropdown.

**Step 4**: Fill in the required fields and any optional ones you need. Every field is described in the [Field reference](https://userguide.qualytics.io/data-quality-checks/entity-resolution/how-tos/create-a-check/#field-reference) above.

**Step 5**: 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/entity-resolution/troubleshooting/#validation-fails-when-creating-the-check).

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

> **Tip: Review the clusters before trusting the threshold**
>
> The first run is a calibration run. Open the resulting clusters in the Entity Resolution Recipe and check whether records that landed together really are the same entity, then adjust the threshold or the weights. See [Scan and Remediate](https://userguide.qualytics.io/recipes/entity-resolution/deep-dive/scan-and-remediate/) in the Entity Resolution Recipe.

*Last updated: November 10, 2026.*
