What matching actually looks like¶
Every verdict and every number on this page was produced by running the pair through arche, not written by hand. Reproduce any of them with the snippet at the bottom.
The point of showing them together is that the hard cases rhyme across entity types. A hospital in Birmingham, a cooperative in Sefwi Wiawso and a flash drive on a retail site fail in the same four ways: the names agree and the things differ, the names differ and the things agree, everything agrees except one field that turns out to decide it, or nothing decides it and the honest answer is look at this one.
That third outcome. review. Is a first-class answer here, not a failure to reach one. Roughly a third of the examples below land on it, and most of those are cases where a matcher that only says yes or no would have to say something false.
Organisations, and the case that breaks every signal at once¶
Cocoa, coffee and tea supplier reconciliation
Kuapa Kokoo Cooperative Society
Kuapa Kokoo Farmers Union
name 1.00 · tftoken 1.00 · entity_class conflict — strip the legal form from both and the names are identical: kuapa kokoo. A society and the union above it are different parties, and nothing in the strings can tell you so. Only the declared class refutes it.
Nyeri Hill Factory (site)
Nyeri Hill Tea Factory Co Ltd (operator)
name 0.95 · geo 1.00 at 0.0 km · entity_class conflict — the largest false-merge risk in supply-chain data. The site and the company that operates it share a name and a coordinate, so every string and spatial signal points the wrong way at once, and stripping the shared form leaves them more alike, not less. Merging them destroys the link between a plot and the party accountable for it, which is the only thing a due-diligence chain exists to establish.
Sefwi Wiawso Cooperative Society
Sefwi Wiawso Co-operative Society Ltd
score 1.00 — Co-operative Society and Cooperative Society Ltd are two spellings of one legal form. Both reduce to sefwi wiawso, and the form carries none of the score.
Touton Negoce SARL RC-88421
Touton Negoce RC-88421
registration_id 1.00 — a company number is the one exact identity signal most supplier files carry, and it settles the pair without the names having to agree on a format.
Central Cooperative Society
Central Cooperative Society
score 1.00 but distinctive_max 0.59 — byte-identical strings, and still not a merge. The score says the names agree; the distinctiveness says agreeing on Central is not evidence of identity, because a population table knows how ordinary that word is. Before the table shipped, this pair merged at 1.00.
Places, in two countries¶
The same three failure modes, on health facilities in the UK and Nigeria.
Facility and place matching
Queen Elizabeth Hospital
Queen Elizabeth Hospital Birmingham
name 0.94 · 0.06 km apart · type match — one register appends the city, the other does not. The coordinates make the qualifier redundant rather than contradictory.
Royal Infirmary (Edinburgh)
Royal Infirmary (Manchester)
name 1.00 · 282.31 km apart · geo conflict — identical names, and two different hospitals. Distance is a physical constraint rather than a preference, so it refutes here instead of merely scoring low. Note it demotes to review, never to no: distance says a human must look.
An Nur Specialist Hospital
Al Noury Specialist Hospital
name 0.93 · 0.03 km apart · tftoken 0.25 — the same Arabic name transliterated two ways, 30 metres apart, and arche still declines to merge it automatically. Character overlap is weak and the shared tokens are not rare enough to carry it alone. This is the honest version of a result often quoted as a win: the pair reaches a human with the evidence attached, rather than being silently fused or silently dropped.
People¶
Person matching
Oluwaseun Adebayo +234 801 234 5678
Olusegun Adebayo +234 801 234 5678
name 0.91 · phone 1.00 — a shared phone number is strong, and Oluwaseun and Olusegun are two different Yoruba given names, not two spellings of one. A household phone is shared; a name is not. Review is the correct answer and a confident merge would be a wrong one.
Amara Nwosu 12 Awolowo Road, Ikoyi, Lagos
Chidi Nwosu 12 Awolowo Road, Ikoyi, Lagos
address 1.00 · name 0.70 — same surname, same address, different people. Address is a supporting signal: it amplifies a decision, it never manufactures one.
Products¶
Product matching
Netgear ProSafe 16-Port Gigabit Switch JGS516
NETGEAR JGS516 ProSafe 16 Port Switch
code 1.00 · name 0.80 — word order, capitalisation and hyphenation all differ. JGS516 is a rare code shared by both, and rarity is what makes it identity-bearing rather than merely common ground.
Not every pair reaches a comparator. SanDisk Cruzer Blade 16GB against the same drive at 32GB is never proposed as a candidate at all — they share no rare token, so blocking drops the pair before scoring. The right answer for the wrong reason, and worth knowing when you read a recall figure.
One messy record against several plausible answers¶
Pairwise matching assumes you already know which two records to compare. Often you do not. You have one string and a shortlist, which is a different problem with a different failure mode.
Ranking candidates
Messy record
FLAT 3 ST LEGER HOUSE GREAT LINFORD MK14 5HA
Candidates
GREAT LINFORD HOUSE 1 ST LEGER COURT GREAT LINFORD MK14 5HA3 ST LEGER HOUSE 4A ST LEGER COURT GREAT LINFORD MK14 5HA3 ST LEGER COURT GREAT LINFORD MK14 5HA
All three share the postcode, and the postcode therefore decides nothing. Candidate 3 is a different building on the same court; candidate 1 shares almost every token in a different arrangement. What separates them is which tokens are rare and which structural role each one plays — HOUSE versus COURT is the distinction the ranking turns on, and it is one token wide.
Reproduce any of these¶
from arche.resolve import crosswalk
a = [{"id": "a", "name": "Nyeri Hill Factory",
"entity_class": "SITE", "lat": -0.42, "lon": 36.95}]
b = [{"id": "b", "name": "Nyeri Hill Tea Factory Co Ltd",
"entity_class": "OPERATOR", "lat": -0.42, "lon": 36.95}]
result = crosswalk(a, b, entity="organisation", id_field="id")
edge = result["matches"][0]
print(edge["decision"], edge["score"], edge["distinctive_max"])
print(edge["evidence"])
Swap entity= for place, person, product_electronics or artist. Every edge carries its evidence, a reproducible decision_id, and can be signed and re-verified by someone who does not trust you.
The pattern underneath¶
Read the five sections together and the same three rules are doing the work each time.
A shared string is not a shared identity. Central and Central are identical and prove nothing; JGS516 and JGS516 are identical and prove almost everything. The difference is rarity, and rarity is a fact about a population rather than about the two records in front of you.
A supporting signal may amplify a decision and may never manufacture one. Geography, address and containment can lift a well-evidenced pair over the line. None of them can carry a weak name across it, which is why two people at one address stay unmerged, and why a site sitting exactly on top of its operator is still two parties.
Refusal is an answer. Every review above is a case where the available evidence genuinely does not settle it. Saying so, with the numbers attached, is more useful than a confident verdict that happens to be wrong, and it is the difference between a queue a person can work through and a merge nobody can defend.