DATASET MATCHING

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.

namecity
Rahul SharmaAhmedabad
Priya PatelSurat

Target CSV

Dataset containing potential matches.

full_namelocation
Rahul S SharmaAhmedabad
Priya P PatelSurat

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.

typescript
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.

SourceTargetWeight
namefull_name0.7
citylocation0.3
typescript
const 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.

OptionDefaultDescription
fieldsRequiredMaps source columns to target columns. Each field accepts sourceKey, targetKey, and an optional weight.
methodjaro-winklerSimilarity algorithm used to compare mapped values.
threshold0.7Minimum overall similarity score required for a candidate. Must be between 0 and 1.
topK1Maximum 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.
typescript
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.

levenshtein
damerau-levenshtein
jaro
jaro-winkler
jaccard
dice
cosine
soundex
metaphone

Jaccard 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.

OptionDefaultDescription
delimiterAutoCharacter used to separate CSV columns.
skipEmptyLinestrueSkips empty lines. Can also be set to greedy.
typescript
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.

PropertyDescription
matchesMatching results for each source record.
unmatchedSource records without qualifying candidates.
totalSourceRecordsNumber of parsed source records.
totalTargetRecordsNumber of parsed target records.
sourceHeadersHeaders detected in the source CSV.
targetHeadersHeaders detected in the target CSV.
parseErrorsParsing 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.

typescript
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.

Try it yourself

Explore CSV Record Matching

Upload two datasets, map their columns, configure matching, and inspect the results in the interactive playground.

Open playground