Skip to content

Entity Resolution FAQ

Common questions about field roles, comparison types, clustering, Recipe remediation, and anomaly reporting.

Behavior

How does Entity Resolution decide that two records are the same entity?

Block fields first determine which records are eligible to be compared. The platform then scores every candidate pair across the weighted comparison fields and treats the pair as a match when its composite score meets the composite match threshold.

Matching pairs form connected clusters. If A matches B and B matches C, all three belong to the same cluster even when A and C do not match directly.

What is the difference between a block field and an exact comparison field?

A block field is a hard boundary. Records with different values are never compared, and no amount of similarity on other fields can override the disagreement.

An exact comparison field contributes weighted evidence. Equal values score 1.0; different values score 0.0. Other comparison fields can still provide enough evidence for the pair to match.

Use a block field for a boundary with no valid exceptions, such as a tenant. Use an exact comparison helper for fields such as industry or country when agreement matters but should not be absolute.

How should I balance name, industry, and geography?

Give the strongest identifier, usually name, the highest weight. Add industry and geography as exact comparison fields with lower weights. Choose a threshold that rejects a perfect name match when both contextual fields disagree, while allowing a slightly different name when both agree.

For example, weights of 4 for name, 2 for industry, and 1 for country give a perfect name with two disagreements a score of 4 / 7, or about 0.57. A threshold of 0.85 rejects that pair.

What does the composite match threshold control?

The threshold is the cutoff for treating a pair as a match. A threshold of 0.7 requires a weighted composite score of at least 70%. Lowering the threshold tolerates more variation and creates larger clusters. Raising it requires stronger agreement and creates smaller clusters. The default is 0.7.

How are NULLs treated?

A record with NULL in a block field cannot be paired. NULL on either side of a comparison field contributes 0.0 for that field, while its weight remains part of the composite. The pair can still match if its other comparison fields provide enough evidence.

Does the filter clause run before or after entity resolution?

Before. The platform applies the filter first, then blocking, scoring, and clustering to the remaining rows. This lets you scope a check to a meaningful subset, such as active records.

Recipe and Golden Sets

Where do I configure Block Fields in the Recipe?

Blocking fields are an advanced, optional setting alongside the distinction field. Expand Fields that segment possible duplicates with high confidence. to select them. Leave the setting collapsed and empty when the data has no true boundary.

Compare Fields remain a separate primary step because they define the weighted evidence used to decide whether an eligible pair matches. When AgentQ is available, it recommends each set separately and recommends blocking fields only after you expand the advanced setting.

Can AgentQ select multiple records from a cluster?

No. AgentQ recommends one best-fit record from each cluster. Only you can decide that more than one row should be retained because the clusters come from deterministic check results.

What happens when I keep multiple records from a cluster?

Every row selected in the Keep as golden column is retained. Unselected rows in the cluster are excluded as duplicates.

For example, if A and B are duplicates but C is a different entity, select the preferred record from A or B and also select C. Both selected rows are written to the golden set.

Does accepting an AgentQ recommendation clear my other selections?

No. Accepting the recommendation selects the suggested row and preserves any other rows you selected in that cluster.

Anomaly Reporting

Which rows appear in the Shape Anomaly's Source Records?

Source Records include only clusters where the distinction field has more than one value. Within each non-compliant cluster, one example row is shown for each distinct value of the distinction field.

What is the _qualytics_entity_id column?

It is the cluster identifier assigned to each record. Records with the same _qualytics_entity_id were identified as the same entity. The column is system-managed and appears in Source Records to show cluster boundaries.

What does the Shape Anomaly message look like?

N records were resolved to D distinct entities (composite threshold T: field_a (w=W), field_b (w=W) ...). K of those entities are assigned more than one value of <distinction_field>
  • N is the number of distinct records analyzed.
  • D is the number of clusters produced.
  • T is the composite match threshold.
  • K is the number of clusters with more than one distinction-field value.

When the check uses block fields, the message includes blocked on [...].

Why doesn't Entity Resolution produce a Record Anomaly?

Entity Resolution is a shape-only rule type. The violation belongs to a cluster of records rather than one individual field value.

Configuration

Is Coverage supported?

No. A cluster is either compliant or non-compliant, so the form and API do not accept a coverage value.

Can a check mix block fields, fuzzy comparisons, and exact comparisons?

Yes. For example, tenant can be a block field, name can use fuzzy comparison, and industry can use exact comparison. Only the block field is a hard boundary. Both comparison fields contribute to the weighted score.

Can the same field appear more than once?

No. Each target field has one role and one comparison type. A duplicate field name is rejected.

Does Custom Anomaly Description work for Entity Resolution?

No. Custom Anomaly Description affects Record Anomaly messages. Entity Resolution emits only Shape Anomalies, which use a fixed message format.

Migration

How were existing multi-field checks migrated?

Existing checks were migrated automatically to separate field role from comparison type:

  • A former exact target field becomes a Block field with exact comparison, preserving its hard-boundary behavior.
  • A former fuzzy, absolute, relative, offset, or granularity target field becomes a Compare field with the same comparison behavior and weight.

The migration preserves how stored checks execute. You can edit a migrated check to turn an exact blocker into a weighted exact comparison helper when that better matches the data.

What about checks created before multi-field Entity Resolution?

Those checks continue to use one String comparison field with their previous fuzzy settings. Their composite threshold was derived from the previous spelling threshold so accepted record pairs remain consistent.

Did the API payload change?

Yes. Every target field now uses type, role, and comparison_type. Scripts and integrations must send the current target_fields structure. Retired or unsupported properties are not accepted by the public API. See the API for the current payload.

  • Introduction: formal definition, field roles, comparison types, and field scope.
  • How It Works: blocking, weighted comparison, clustering, Recipe guidance, and golden-set behavior.
  • Examples: production scenarios with sample data and resulting anomalies.
  • API: current public payload and field reference.