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
namefullNamecitylocation02. Field comparison
Name
Pavan Kapadiya ↔ Pawan Kapadia
City
New Delhi ↔ Delhi
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.
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.
namefullNamecitylocationemailemailAddressConfigure matching
Configure the similarity method, field weights, matching threshold, candidate count, and normalization options.
| Option | Description |
|---|---|
fields | Maps source fields to their corresponding target fields. Each field can have an optional weight. |
method | Selects the similarity algorithm used for comparing field values. |
threshold | Sets the minimum similarity score required for a candidate to qualify as a match. |
topK | Controls the number of top candidates returned. |
normalization | Preprocesses mapped field values before similarity comparison. |
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 practicesKeep these points in mind when matching records.
Map equivalent fields
Connect corresponding properties between datasets, even when their field names differ.
Choose appropriate weights
Give more importance to fields that are more useful for identifying the same entity.
Tune the threshold
Test different threshold values against your data to control which candidates qualify as matches.