How Entity Resolution Checks Work

Definition

Asserts that records with similar values across the configured target fields are resolved as the same entity and share a single distinction field value.

Overview

Entity Resolution is a multi-field rule. You pick one or more target fields that describe the entity (for example, name, industry, country, or phone), assign each field a blocking or comparison role, and choose how its values are compared. The platform clusters records whose weighted comparison score meets the composite match threshold. Each cluster is assigned a unique cluster identifier (_qualytics_entity_id).

Once clusters are built, the rule checks the distinction field. Every record in the same cluster must share the same value for that field. Clusters that hold more than one value are flagged.

Typical use cases:

• Match customer or company records with name and address variations.
• Consolidate duplicate entities across systems that record slightly different spellings.
• Identify fuzzy matches for deduplication before pushing records downstream.

Field Scope

Calculated: Entity Resolution does not take a fixed list of fields. Instead, the platform derives the evaluated fields from the target fields you configure. Each entry names one field, its role, and its comparison type. The distinction field is configured separately.

Distinction Field: Accepted Types

Target Field Roles

Target Field Types and Comparisons

The same exact comparison behaves differently by role. With the Block role, a disagreement prevents the pair from being scored. With the Compare role, a disagreement contributes 0.0, but stronger evidence from other comparison fields can still make the pair a match.

Anomaly Types

How the Check Evaluates Entity Resolution

Every Entity Resolution check follows the same five-step flow:

1. Apply the filter clause. Only rows that match the filter continue. Rows outside the filter cannot cause a violation.
2. Apply block fields. Records must have the same value on every field whose role is Block. A disagreement prevents the records from becoming a candidate pair.
3. Score comparison fields. Each field whose role is Compare produces a score. The selected comparison type controls how the score is calculated, and the field's weight controls its influence on the composite score.
4. Build clusters from matching pairs. A pair matches when its composite score is greater than or equal to the composite match threshold. Matches are grouped transitively: if A matches B and B matches C, all three records belong to one cluster even when A and C do not match directly.
5. Enforce the distinction field. A cluster is non-compliant when its records contain more than one value of the distinction field.

Block fields are evaluated before comparison fields. A pair that disagrees on a block field is never scored, regardless of its other similarities. An exact comparison field behaves differently: disagreement scores 0.0, but evidence from other comparison fields can still lift the composite score above the threshold.

Field Role and Comparison Type

Every target field has four common settings:

• Field name: the source field to evaluate.
• Type: String, Numeric, or DateTime.
• Role: Block or Compare.
• Comparison type: the type-specific method used to compare values.

Compare fields also have a weight. Block fields do not contribute to the composite score, so their weight is not used.

Block Fields

A block field is an exact hard boundary. Records with different values are not considered as a pair. Good block fields represent rules with no reasonable exceptions, such as tenant, legal entity, or another partition where cross-boundary matches would always be wrong.

Blocking can also reduce the number of pairs that must be scored. However, a field such as Country should not be a blocker when cross-country matches are rare but still possible. Configure it as an exact comparison field instead.

String Comparisons

Optional fuzzy string settings:

• pair_substrings promotes the field score to 1.0 when one value contains the other, such as "ACME" and "ACME Inc.".
• pair_homophones promotes the field score to 1.0 when the values sound alike, such as "Catherine" and "Katherine".
• consider_term_frequency gives uncommon tokens more influence than common tokens.

Numeric Comparisons

Datetime Comparisons

Weights and the Composite Score

For each candidate pair, the platform multiplies every comparison field's score by its weight, adds the weighted scores, and divides by the total comparison weight:

composite = sum(score_i * weight_i) / sum(weight_i)

Increasing a field's weight gives it more influence. When comparison fields are configured, at least one must have a positive weight.

For example, consider these comparison fields:

If the name matches perfectly but industry and country both differ, the composite score is 4 / 7, or about 0.57. At a threshold of 0.85, the pair does not match. If industry and country agree, a slightly different name can still clear the threshold. This lets categorical fields provide positive and negative evidence without creating an absolute boundary.

The Composite Match Threshold

The composite_match_threshold is a value between 0.0 and 1.0 (default 0.7):

• Lower threshold, such as 0.6: tolerates more variation. More pairs match, clusters grow larger, and unrelated records are more likely to be grouped.
• Higher threshold, such as 0.9: requires stronger evidence. Clusters stay smaller, but real variations may be missed.

Start at the default, inspect the first scan's Source Records, and adjust the threshold or weights until the clusters reflect your definition of the same entity.

NULL Values

• A record with NULL in any block field cannot be paired.
• A comparison field with NULL on either side contributes 0.0, while its weight remains part of the composite score.

A pair with a NULL comparison value can still match when its other comparison fields provide enough evidence.

How Clusters Become Entities

Pairs that meet the threshold form connected clusters:

• A and B belong to the same cluster when they match directly.
• A, B, and C belong to the same cluster when A matches B and B matches C, even if A and C do not match directly.

Each cluster receives a _qualytics_entity_id. This system-managed column appears in Source Records so records from the same cluster can be identified.

The Filter Clause

The filter clause is a SQL WHERE expression applied before blocking and scoring. Only rows that match the filter enter resolution. Rows outside the filter cannot be clustered, and they cannot be reported.

Common uses:

• Limiting resolution to one source system or region (source_system = 'crm').
• Excluding records already merged by an upstream process (merged_into IS NULL).
• Restricting the check to a recent partition (updated_at >= '2026-01-01').

The anomaly message does not repeat the filter expression. The record count it reports is taken after the filter runs, as described on the Anomaly Reporting page.

Coverage

Entity Resolution does not use a coverage threshold. The check evaluates clusters rather than individual rows, so there is no passing fraction to tolerate. Any cluster that holds more than one value of the distinction field makes the check fail with a single Shape Anomaly. The composite match threshold is the setting that controls how tolerant the check is. Raise it to cluster more conservatively, or lower it to accept more variation. The form shows no Coverage slider for this rule type, and the API rejects a coverage value other than the default.

Using the Entity Resolution Recipe

The Entity Resolution Recipe is a guided flow around this rule type that builds the check, validates it on a sample, scans, and writes a golden set to the enrichment destination. It is documented end to end in the Entity Resolution Recipe section. How the rule's fields appear inside the recipe is covered on Build and Validate, and how golden records are chosen from each cluster on Scan and Remediate.

See Also