Skip to main content
The $fuzzy operator matches terms that are similar but not identical to the search term. This is useful for handling typos, misspellings, and minor variations in user input.

​
Levenshtein Distance

Fuzzy matching uses Levenshtein distance (also called edit distance) to measure similarity between terms. The distance is the minimum number of single-character edits needed to transform one word into another. These edits include:
  • Insertions: Adding a character (“headphone” → “headphones”)
  • Deletions: Removing a character (“headphones” → “headphone”)
  • Substitutions: Replacing a character (“headphones” → “headphonez”)
For example, the Levenshtein distance between “headphons” and “headphones” is 1 (one insertion needed).

​
Distance Parameter

The distance parameter sets the maximum Levenshtein distance allowed for a match. The default is 1, and the maximum allowed value is 2.
DistanceMatches
1Words with 1 edit (handles most single typos)
2Words with up to 2 edits (handles more severe misspellings)
Higher distances match more terms but may include unintended matches, so use distance 2 only when needed.

​
Transposition Cost

A transposition swaps two adjacent characters (e.g., “teh” → “the”). By default, a transposition counts as 1 edit. Setting transpositionCostOne: false counts transpositions as two edits (one deletion + one insertion) instead. For example, searching for “haedphone” to find “headphone”:
  • With transpositionCostOne: true: Distance is 1 (swap counts as 1)
  • Without transpositionCostOne: Distance is 2 (swap “ae” → “ea” costs 2)
This is useful when users commonly transpose characters while typing quickly.

​
Prefix Matching

Setting prefix: true enables fuzzy prefix matching, which matches terms that start with a fuzzy variation of the search term. This combines the typo tolerance of fuzzy matching with prefix matching for incomplete words. For example, searching for “headpho” with prefix: true:
  • Matches “headphones” (prefix match)
  • Matches “headphone” (prefix match)
  • Matches “haedphones” with transpositionCostOne: true (fuzzy prefix, handles typo + incomplete word)
This is particularly useful for search-as-you-type autocomplete where users may have typos in partially typed words.

​
Multiple Words

When you provide multiple words to $fuzzy, each word is matched with fuzzy tolerance and combined using a boolean $must query. This means all terms must match (with their respective fuzzy tolerance) for a document to be returned. For example, searching for “wireles headphons” will match documents containing both “wireless” and “headphones”, even with the typos.

​
Compatibility

Field TypeSupported
TEXTYes
U64/I64/F64No
DATENo
BOOLNo

​
Examples

// Simple fuzzy (distance 1, handles single typos)
// Matches "headphone" even with the typo "headphon"
await products.query({
  filter: {
    name: { $fuzzy: "headphon" },
  },
});

// Custom distance for more tolerance
// "haedphone" is 2 edits away from "headphone" without taking transposition into account
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedphone",
        distance: 2,
        transpositionCostOne: false,
      },
    },
  },
});

// Handle character transpositions efficiently
// "haedphone" has swapped "ae", with transpositionCostOne this is 1 edit
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedphone",
        distance: 1,
        transpositionCostOne: true,
      },
    },
  },
});

// Combine prefix with transposition for robust autocomplete
// Handles both typos and incomplete input like "haedpho" → "headphones"
await products.query({
  filter: {
    name: {
      $fuzzy: {
        value: "haedpho",
        prefix: true,
      },
    },
  },
});

// Multiple words - matches documents containing both terms (with fuzzy tolerance)
// Matches "wireless headphones" even with typos in both words
await products.query({
  filter: {
    name: { $fuzzy: "wireles headphons" },
  },
});