CSV Record Matching
Find corresponding records across two CSV datasets using configurable field mapping and string similarity algorithms. MatchForge handles CSV parsing, candidate scoring, ranking, and result export through a simple API.
What is CSV record matching?
CSV record matching identifies similar records across two datasets. Instead of requiring exact equality, MatchForge compares selected columns using string similarity algorithms. This is useful when datasets contain spelling differences, inconsistent formatting, or different column names.
Source CSV
Records you want to find matches for.
Target CSV
Dataset containing potential matches.
How it works
MatchForge parses both CSV inputs, compares mapped columns, calculates a weighted score for each candidate, and returns the best qualifying candidates.
01. Parse CSV files
Read headers and records from both CSV datasets.
02. Map and compare fields
Compare corresponding columns using the selected similarity method.
03. Calculate weighted scores
Combine individual field scores using their configured weights.
04. Rank candidates
Filter candidates by threshold, sort by score, and return the top K.
Each source record is compared independently against the target dataset. A target record can therefore appear as a candidate for multiple source records. This is not a one-to-one assignment algorithm.
Basic usage
Pass the contents of two CSV files to matchCSV() and specify which columns should be compared. The first row of each CSV is treated as its header.
import {
matchCSV,
exportMatches,
} from "@matchforge/core";
const sourceCSV = `name,city
Rahul Sharma,Ahmedabad
Priya Patel,Surat
Amit Shah,Vadodara`;
const targetCSV = `full_name,location
Rahul S Sharma,Ahmedabad
Priya P Patel,Surat
Amit Shah,Vadodara`;
const result = matchCSV(sourceCSV, targetCSV, {
fields: [
{ sourceKey: "name", targetKey: "full_name" },
{ sourceKey: "city", targetKey: "location" },
],
});
console.log(result.matches);
const csv = exportMatches(result);The returned result includes candidate matches, unmatched source records, record counts, detected headers, and parsing errors.
Field mapping and weights
Different datasets may use different names for the same information. Use sourceKey and targetKey to map corresponding columns.
namefull_name0.7citylocation0.3const result = matchCSV(sourceCSV, targetCSV, {
fields: [
{
sourceKey: "name",
targetKey: "full_name",
weight: 0.7,
},
{
sourceKey: "city",
targetKey: "location",
weight: 0.3,
},
],
});Each field has an optional weight. Fields without a weight use 1. MatchForge calculates the weighted average using available field scores. Missing, null, and empty values are skipped. Fields with a weight of zero are also skipped.
Matching configuration
Configure the similarity algorithm, minimum score, candidate limit, and preprocessing behavior.
| Option | Default | Description |
|---|---|---|
fields | Required | Maps source columns to target columns. Each field accepts sourceKey, targetKey, and an optional weight. |
method | jaro-winkler | Similarity algorithm used to compare mapped values. |
threshold | 0.7 | Minimum overall similarity score required for a candidate. Must be between 0 and 1. |
topK | 1 | Maximum number of qualifying candidates returned for each source record. Must be a positive integer. |
normalization | {} | Preprocessing options applied before comparing string values. |
algorithmOptions | {} | Additional configuration for supported similarity algorithms. |
const result = matchCSV(sourceCSV, targetCSV, {
fields: [
{ sourceKey: "name", targetKey: "full_name" },
{ sourceKey: "city", targetKey: "location" },
],
method: "jaro-winkler",
threshold: 0.8,
topK: 3,
normalization: {
lowercase: true,
trim: true,
removeAccents: true,
},
});The default method is jaro-winkler, the default threshold is 0.7, and the default topK is 1. Threshold must be between 0 and 1, and topK must be a positive integer.
Supported similarity methods
Choose one similarity algorithm for the mapped fields in a matching operation.
levenshteindamerau-levenshteinjarojaro-winklerjaccarddicecosinesoundexmetaphoneJaccard and Dice use q-gram similarity. Additional q-gram configuration can be supplied through algorithmOptions.
CSV parsing options
Configure parsing independently for both inputs using sourceParseOptions and targetParseOptions.
| Option | Default | Description |
|---|---|---|
delimiter | Auto | Character used to separate CSV columns. |
skipEmptyLines | true | Skips empty lines. Can also be set to greedy. |
const result = matchCSV(sourceCSV, targetCSV, {
fields: [
{ sourceKey: "name", targetKey: "full_name" },
],
sourceParseOptions: {
delimiter: ";",
skipEmptyLines: true,
},
targetParseOptions: {
delimiter: ",",
skipEmptyLines: true,
},
});
console.log(result.parseErrors);CSV values are parsed as strings. Parsing errors are available separately under result.parseErrors.source and result.parseErrors.target.
Understanding the results
Each source record has a result containing its original data, record number, qualifying candidates, and match status.
| Property | Description |
|---|---|
matches | Matching results for each source record. |
unmatched | Source records without qualifying candidates. |
totalSourceRecords | Number of parsed source records. |
totalTargetRecords | Number of parsed target records. |
sourceHeaders | Headers detected in the source CSV. |
targetHeaders | Headers detected in the target CSV. |
parseErrors | Parsing errors from both CSV inputs. |
Candidate information
Each candidate contains the target record, target record number, overall similarity score, selected method, and individual field scores.
EXAMPLE CANDIDATE
Target record
2
Score
0.92
Method
jaro-winkler
Matched
true
Record numbers are one-based positions in the parsed records, excluding the header row. A source record is matched when at least one candidate meets the threshold.
Export matching results
Use exportMatches() to convert matching results into a CSV string. The exported data includes record numbers, match status, score, method, and the original source and target fields.
import {
matchCSV,
exportMatches,
} from "@matchforge/core";
const result = matchCSV(sourceCSV, targetCSV, {
fields: [
{ sourceKey: "name", targetKey: "full_name" },
],
});
const outputCSV = exportMatches(result);
// Use a custom delimiter
const tabSeparated = exportMatches(result, {
delimiter: "\t",
});The output delimiter can be customized through the optional export options object. The default delimiter is a comma.
Best practices
Choose informative fields
Use columns that help distinguish records, such as names, email addresses, or locations.
Set meaningful weights
Give greater weight to fields that are more reliable for identifying the same entity.
Tune the threshold
A higher threshold is more restrictive, while a lower threshold allows more candidates.
Inspect multiple candidates
Increase topK when you want to review several possible matches for each source record.
Explore CSV Record Matching
Upload two datasets, map their columns, configure matching, and inspect the results in the interactive playground.
Open playground