ListMatchGenie

One-to-one vs one-to-many matching

By default, multiple source rows can match the same master row. Enable one-to-one matching to force unique pairing, useful for merging workflows and assignment problems.

By default, ListMatchGenie allows the same master row to be the best match for multiple source rows. If two source rows both look like your customer "Jane Smith", both will match to Jane. This is one-to-many matching.

In some workflows this is wrong. If you're merging CRM records, two source rows claiming the same master means one of them is a duplicate that shouldn't exist. You'd want to force each master to be matched by at most one source — one-to-one matching.

This page covers both modes and when to use each.

Default: one-to-many

Each source row is scored independently against the master and takes its best candidate. Master rows can be hit by multiple source rows.

Behavior:

  • Source row 1 matches master row 42
  • Source row 2 matches master row 42 (same)
  • Source row 3 matches master row 42 (same)
  • All three source rows have _lmg_master_row_id = 42

Use cases:

  • Enrichment — you're attaching master data to source rows; it's fine if many sources attach to the same master.
  • Lead-to-customer matching — many leads can be the same customer.
  • Many-to-one lookups generally.

Enabling one-to-one

Check the One-to-one matching box on the Configure step.

Behavior:

  • Source row 1 matches master row 42 (best score)
  • Source row 2 also wanted master row 42, but couldn't get it — takes its second-best candidate instead (or becomes unmatched)
  • Source row 3 similar

The engine uses the assignment optimization to find the globally optimal assignment: the set of source-to-master pairs that maximizes the sum of scores subject to each master being claimed at most once.

This is a well-studied assignment problem with known optimal solutions. It's not "first come first served" — the engine finds the global optimum, which may mean source row 1 doesn't get master row 42 if source row 2 had an even better score there.

Use cases:

  • CRM merge workflows — each source lead should merge into at most one master contact.
  • Unique-ID generation — assigning unique identifiers from a pool.
  • Territory assignment — each account gets at most one sales rep.
  • Reconciliation between two unique-identity systems.

Performance implications

One-to-one matching adds a final pass (the assignment optimization). On typical data this adds 10–30% to total match time.

For very large files (100,000+ rows on each side), the assignment pass can be significant. The engine applies sparse optimizations (only considering pairs above a minimum score threshold), which keeps runtime manageable, but it's slower than one-to-many.

Max candidates per match

Independent of one-to-one/many, you can configure max candidates per match — how many top candidates to return per source row:

Max candidates1–10Default: 1

When 1, you get the best match only (standard). When higher, you get up to N top candidates per source row.

Max candidates > 1 is useful for:

  • Research and discovery — you want to see what else could have matched
  • Side-by-side review workflows where the reviewer decides among candidates
  • Appending "also-matched" columns for analysis

When max candidates > 1 and one-to-one is enabled, the assignment optimization enforces uniqueness at the top candidate; lower candidates can still reuse master rows.

Tie-breaking in one-to-one

When two source rows tie exactly for the same master:

  • The assignment optimization deterministically picks one based on the surrounding assignment landscape.
  • The picked source row gets the match; the other proceeds to its next-best candidate.

This is reproducible — running the match again produces the same result.

Common pitfalls

Enabling one-to-one with a sparse master

If your master is much smaller than your source and many sources map to the same small set of masters, forcing one-to-one will leave many sources unmatched. Example: 500 new leads mapped to 5 test accounts in a small master — only 5 leads get matched.

Expecting one-to-one to resolve master-file duplicates

If your master file has duplicates (Jane Smith appears at row 42 and row 104), one-to-one matching treats them as different master rows. Source rows will distribute between them; neither becomes "the" match. Dedupe the master first.

Forgetting to enable it

If you're doing a merge workflow and forget to check one-to-one, two source rows can claim the same master. Downstream merge logic may fail or produce duplicates. Always explicitly enable one-to-one for merge workflows.