GoldenMatch

GoldenMatch

Find the rows in your data that are the same person, company or product. No rules to write, no labelled pairs, no model to train.

Zero-config entity resolution for Python. Point it at a CSV or a table: it chooses how to match, shows you what it chose, and merges each group of duplicates into one golden record.

**v3.22.0: Zero-config person dedupe is 18-30x faster, and your records come back as you entered

them.** 250k rows went from 520 s to 18 s with identical clusters (upgrade pulls goldenmatch-native 0.2.3). The unique, duplicate and deduplicated tables now carry your original values instead of standardized ones; keep_original_values=False or --standardized-values restores the old output.

v3.21.0: No false alarms on small files, and no LLM calls you didn't ask for. A correct run on

a small file no longer logs RED "output may be low-precision", and auto-config now turns on the (paid) LLM scorer only when you pass llm_auto=True -- it used to do so whenever an OPENAI_API_KEY or ANTHROPIC_API_KEY happened to be set. If you relied on that, pass llm_auto=True or set llm_scorer in your config.

v3.20.0: Integer ID columns no longer crash zero-config. A CSV whose phone or account column is

plain digits (read as int64) made gm.dedupe(path) and goldenmatch dedupe die with ArrowNotImplementedError in auto-config's blocking; it now runs, and negative evidence on such a column scores instead of silently switching itself off. The CLI summary now says what it counts -- 12 records -> 7 entities (4 duplicate groups) -- and result.total_entities matches it.

---

Try it

pip install goldenmatch

goldenmatch dedupe customers.csv

Take a customers.csv where the same people were entered more than once:

GoldenMatch puts rows 1-3 together as one person and rows 4-5 as another. Thomas Becker and Thomas Baker share a zip code and stay separate. Each group becomes one golden record, built from the best value of each field. The run writes _deduplicated.csv, one row per person (the four golden records plus the three people who had no duplicate), and _golden.csv with the merged records alone.

From Python:

import goldenmatch as gm

result = gm.dedupe("customers.csv") print(result) # DedupeResult(records=12, clusters=4, match_rate=75.0%)

result.deduplicated # one row per person: 7 here result.golden # one merged record per duplicate group result.unique # the records that had no duplicate result.clusters # which input rows belong together result.config # the matching config it chose

Already have the data in memory? gm.dedupe_df(table) takes a pyarrow Table or a polars DataFrame.

What it chose, and how to change it

Nothing here is a black box. On the file above, auto-config matched exactly on email and phone and fuzzily on name and address, and only compared records that share a zip. result.config holds that decision:

• Reuse it on new data: gm.dedupe("next_month.csv", config=result.config).
• Take over with your own rules: gm.dedupe("customers.csv", exact=["email"], fuzzy={"name": 0.85}), or a YAML config. See configuration.

Beyond one file

Your customer data lives in a CRM, a billing system, and three spreadsheets nobody owns. Some records are duplicates. Some are the same company spelled four different ways. Nobody can answer *how many customers do we actually have*, and every dashboard built on top inherits the doubt.

Splink-beating entity resolution, Arrow-native and Rust-fast with zero tuning, feeding a durable identity layer so messy records from every source become stable golden entities with whole-record, Customer-360 provenance.

Zero-config matching that beats expert-tuned Splink head-to-head on messy customer records, in an Arrow-native, Rust-authoritative engine verified from a laptop CSV to a 250M-row dedupe in 11.2 minutes. The identities it produces live in a transaction-native control plane carrying stable entity_ids, per-field provenance, merge/split, and a tamper-evident audit log, all one call away as a Customer 360. It even owns its primitives: byte-identical, faster-than-rapidfuzz / jellyfish / FAISS Rust kernels, not rented dependencies.

Python · TypeScript · SQL, at 4-decimal parity · native in Postgres + DuckDB · edge WASM · 70+ MCP tools · beats hand-tuned Splink · 250M rows in 11.2 min

Pair drilldown in the web workbench: cluster members, field-level diff, and a one-line NL explanation per pair. pip install goldenmatch[web] then goldenmatch serve-ui <project> . More screenshots →

---

What you get: the golden entity

Most entity-resolution tools hand you clusters and stop. GoldenMatch keeps going: it resolves messy records into a durable golden entity, one per real-world customer, that survives re-runs, carries provenance on *every field*, and answers "who is this, and where did each value come from?" in a single call.

• A stable identity, not a throwaway cluster id. Every entity gets a stable entity_id (UUIDv7) that persists across runs as new data arrives. Records are absorbed, entities merge or split, but the id an entity earns is the id downstream systems can rely on. Run-local cluster numbers reshuffle on every run; these don't.
• Whole-record provenance. Every field of the golden record traces back to the source record that won it: which source, when it was last seen, and which survivorship strategy picked it. The values it *didn't* pick stay visible rather than being silently dropped. Provenance is on the whole unified record, not just the match decision.
• Governed by construction. Conflicting values collapse to one best value by an explicit survivorship policy (most-complete · source-priority · most-recent · majority-vote); every identity change lands in an append-only event timeline; and the log is sealed with a hash-chained, tamper-evident audit that a reviewer (or the other language port) can independently verify.

customer_360(entity_id) composes it into one read: golden record, per-field provenance, every linked source record, the event timeline, and the entity's relationship neighborhood:

// customer_360("018f...c2a1")  (trimmed)

{ "entity_id": "018f2b7e-...-c2a1", "confidence": 0.97, "record_count": 3, "sources": ["salesforce", "billing", "support"], "golden_record": { "name": "Ada Lovelace", "email": "ada@analytical.io", "phone": "+1-555-0100" }, "field_provenance": [ { "field": "email", "value": "ada@analytical.io", "winning_source": "billing", "winning_record_id": "billing:8821", "conflicting_values": [ { "value": "ada@ada.dev", "source": "salesforce" } ] }, { "field": "phone", "value": "+1-555-0100", "winning_source": "salesforce" } ], "timeline": [ { "kind": "created", "actor": "pipeline", "recorded_at": "2026-07-30T..." }, { "kind": "absorbed_record", "reason": "matched billing:8821" } ], "relationships": [ { "other_entity_id": "018f...9d0e", "kind": "shares_address" } ] }

What ships today vs. what's emerging. The identity spine is production-grade and in `main`: stable `entit