Matching at a glance
The whole pipeline, end to end.
The pipeline
The moving parts
| Part | Decides | Configured by |
|---|---|---|
| Blocking strategy | Which pairs are worth comparing at all | Attributes plus a transformation, combined into keys |
| Comparison ladder | How well two values agree | An ordered list of levels per attribute |
| Match weight | What that agreement is worth | Two probabilities per level, expressed as a log2 ratio — then adjusted at scoring time for how common the actual value is |
| Thresholds | Merge, review, or ignore | Two numbers on the evidence scale |
| Survivorship rules | Which value wins after a merge | One strategy per attribute |
All five live in a match profile, scoped to one entity type. A tenant can hold several profiles per entity type with one active at a time, which is what makes staged rollout and side-by-side comparison possible.
A worked example
Take the CRM and ERP records from the worked example and score them with the shipped US banking person profile, whose auto-link threshold is 30.0 and whose clerical-review floor is 5.0.
Every weight below is log2(m / u) computed from that profile's own
probabilities. Nothing here is illustrative.
| Attribute | Agreement | Level | m | u | Weight |
|---|---|---|---|---|---|
date_of_birth | 1979-08-22 both | exact | 0.98 | 0.0003 | +11.674 |
phone | +15553001001 both | exact | 0.80 | 0.0001 | +12.966 |
address.line1 | 12 Old Mill Road / 12 Old Mill Rd | exact after standardization | 0.50 | 0.03 | +4.059 |
address.postalCode | 06103 both | exact | 0.55 | 0.06 | +3.196 |
address.city | Hartford both | exact | 0.55 | 0.12 | +2.196 |
address.country | US both | equal | 0.92 | 0.65 | +0.501 |
email | different | mismatch | 0.10 | 0.9979 | −3.319 |
| Subtotal | +31.273 |
Read what those numbers say.
The phone number carries the case — a shared phone is worth nearly 13 points
because two unrelated people sharing one is vanishingly unlikely. Date of birth
is worth almost as much. The address contributes four separate small amounts
rather than one large one, and address.line1 only agrees at all because
standardization expanded Rd to road before anything was compared. The
disagreeing email counted against the pair.
Why the names decide it
The subtotal above is already past the 30.0 auto-link threshold — but it
deliberately omits first_name and last_name, because whether Jon and
Jonathan reach a fuzzy rung or fall through to mismatch is decided by the
comparator at run time, not by reading the profile.
That omission is the whole lesson:
| If the given name… | Contributes | Total | Outcome |
|---|---|---|---|
falls through to mismatch | −4.539 | +26.73 | clerical review |
| reaches a fuzzy rung | ≥ 0 | ≥ +31.27 | auto-link |
One field, on a pair where six other signals already agree, moves this between merged automatically and a human decides. That is not a flaw in the tuning — it is the review band doing its job.
A profile authors m and u. The engine computes log2(m / u) when the level
is created. You will not find a weight field to set.
Note also that these probabilities are priors — deliberate, literature-based starting values, not measurements of your data. The shipped profile says so itself, and tuning is how they stop being guesses.
What you configure, in order
- Entity type and attributes — matching operates on what you have modelled.
- Standardization — normalize values first; the matcher compares canonical forms.
- Blocking strategies — generous enough that true pairs are always proposed.
- Comparison ladders — one per attribute that carries identity.
- Weights — from your own labelled pairs where possible.
- Thresholds — auto-link set for precision, clerical review set for the review capacity you have.
- Survivorship rules — which source wins, per attribute.
Next
Last verified against commit 315eb047 (2026-08-03)