Record matching

Record matching identifies corresponding records across two datasets, even when their values are not exactly identical. MatchForge provides field mapping, weighted matching, and configurable similarity options through matchRecords().

How record matching works

MatchForge compares mapped fields between source and target records, calculates an overall similarity score, and evaluates potential matches against a threshold.

SOURCE RECORD

Pavan Kapadiya

name

New Delhi

city

TARGET RECORD

Pawan Kapadia

fullName

Delhi

location

01. Field mapping

namefullNamecitylocation

02. Field comparison

Name

Pavan Kapadiya ↔ Pawan Kapadia

70% weight

City

New Delhi ↔ Delhi

30% weight

03. Match evaluation

Field similarity scores contribute to an overall matching score according to their weights.

Threshold

0.80

Decision

Qualify if score ≥ threshold

Basic usage

Import matchRecords() and provide your source dataset, target dataset, and field mappings. Field mappings connect properties that may have different names in each dataset.

typescript
import { matchRecords } from "@matchforge/core";

const source = [
  { name: "Pavan Kapadiya", city: "New Delhi" },
  { name: "Rahul Patel", city: "Ahmedabad" }
];

const target = [
  { fullName: "Pawan Kapadia", location: "Delhi" },
  { fullName: "Rahul Patel", location: "Ahmedabad" }
];

const result = matchRecords(source, target, {
  fields: [
    { sourceKey: "name", targetKey: "fullName" },
    { sourceKey: "city", targetKey: "location" }
  ]
});

console.log(result);

Field mapping

Use sourceKey and targetKey to specify which properties should be compared.

Source fieldTarget field
namefullName
citylocation
emailemailAddress

Configure matching

Configure the similarity method, field weights, matching threshold, candidate count, and normalization options.

OptionDescription
fieldsMaps source fields to their corresponding target fields. Each field can have an optional weight.
methodSelects the similarity algorithm used for comparing field values.
thresholdSets the minimum similarity score required for a candidate to qualify as a match.
topKControls the number of top candidates returned.
normalizationPreprocesses mapped field values before similarity comparison.
typescript
const result = matchRecords(source, target, {
  fields: [
    {
      sourceKey: "name",
      targetKey: "fullName",
      weight: 0.7
    },
    {
      sourceKey: "city",
      targetKey: "location",
      weight: 0.3
    }
  ],
  method: "jaro-winkler",
  threshold: 0.8,
  topK: 3,
  normalization: {
    lowercase: true,
    trim: true,
    normalizeWhitespace: true,
    removeAccents: true
  }
});

Normalization is optional. When provided, the same preprocessing options are applied to mapped field values before similarity comparison. If omitted, the default normalization behavior is used. See the preprocessing guide for available options.

Important considerations

Best practices

Keep these points in mind when matching records.

Map equivalent fields

Connect corresponding properties between datasets, even when their field names differ.

01

Choose appropriate weights

Give more importance to fields that are more useful for identifying the same entity.

02

Tune the threshold

Test different threshold values against your data to control which candidates qualify as matches.

03