$fuzzy

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.

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#

Examples#