Skip to main content

Review potential matches

Pairs whose evidence is suggestive but not conclusive are queued for a data steward. This page is that workflow.

Before you start​

  • potential-match.read to see the queue.
  • potential-match.resolve to record any decision — confirm, reject, or defer.
  • entity.merge in addition to potential-match.resolve to confirm a match, since confirming performs the merge.

A caller holding only potential-match.read can read the queue and act on nothing.

1. Open the queue​

The match queue listing pairs awaiting review The match queue. Each row shows the two records, the composite weight, and the tier that weight fell into.

The queue holds every pair that scored into the clerical review band. Each row shows the two records, the composite weight, and the tier.

The composite weight is in log2 evidence units — not a percentage. Higher means more evidence; each whole point doubles it. See how probabilistic scoring works.

2. Read the evidence, not just the score​

A match pair with its per-attribute score breakdown A pair, side by side. Every attribute's contribution is shown — this is the evidence the score is made of.

Open a pair and you see the two records side by side with a per-attribute breakdown: which level each attribute resolved to, and what it contributed.

This breakdown is the point of the review. The composite weight tells you how much evidence there is; the breakdown tells you what kind, which is what you actually need in order to judge:

  • A pair carried almost entirely by one attribute deserves suspicion, however high the total.
  • A pair where several independent attributes each contribute modestly is usually a genuine match.
  • A strongly negative contribution — a disagreeing identifier — deserves more attention than a high total, because identifiers do not usually disagree by accident.
Values may be masked

Field masking applies here as everywhere else. If an attribute you need in order to judge the pair is masked, you lack permission to see it — request access rather than deciding on partial information.

3. Decide​

DecisionWhat happens
ConfirmRecords merge. Survivorship picks winning values; crosswalks, relationships, and consent re-point to the survivor. Reversible.
RejectRecorded as a confirmed non-match, so the pair is not queued again.
LeaveStays queued.

Rejections are as valuable as confirmations: they become labelled non-matches, which is exactly what threshold tuning needs — and hard negatives are the scarcest input there.

4. If a merge was wrong​

Unmerge it. The absorbed records are restored with the state they carried, and the reversal is recorded. Merges are reversible by design precisely so a steward can act decisively without fear of an irreversible mistake.

Working the queue well​

  • Sort by composite weight and work downward. The heaviest pairs are usually clear confirmations; clearing them quickly leaves time for the genuinely ambiguous ones.
  • A queue that never empties is a configuration signal. Persistent volume usually means the clerical review threshold is too low, or an attribute is contributing evidence it should not.
  • Recurring near-identical pairs usually indicate a standardization gap — the same value arriving in two forms — better fixed upstream than decided repeatedly by hand.

Next​

Last verified against commit 315eb047 (2026-08-03)