> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# $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.

| Distance | Matches |
| - | - |
| 1 | Words with 1 edit (handles most single typos) |
| 2 | Words 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`](../boolean-operators/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 Type | Supported |
| - | - |
| TEXT | Yes |
| U64/I64/F64 | No |
| DATE | No |
| BOOL | No |
| KEYWORD | No |
| FACET | No |

### Examples

> [tab] TypeScript
>
> ```ts theme={"system"}
> // 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" },
>   },
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> # Simple fuzzy (distance 1, handles single typos)
> products.query(filter={"name": {"$fuzzy": "headphon"}})
>
> # Custom distance for more tolerance
> products.query(filter={"name": {"$fuzzy": {"value": "haedphone", "distance": 2, "transpositionCostOne": False}}})
>
> # Handle character transpositions efficiently
> products.query(filter={"name": {"$fuzzy": {"value": "haedphone", "distance": 1, "transpositionCostOne": True}}})
>
> # Combine prefix with transposition for robust autocomplete
> products.query(filter={"name": {"$fuzzy": {"value": "haedpho", "prefix": True}}})
>
> # Multiple words - matches documents containing both terms (with fuzzy tolerance)
> products.query(filter={"name": {"$fuzzy": "wireles headphons"}})
> ```

> [tab] Redis CLI
>
> ```bash theme={"system"}
> # Simple fuzzy (distance 1, handles single typos)
> SEARCH.QUERY products '{"name": {"$fuzzy": "headphon"}}'
>
> # Custom distance for more tolerance
> SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedphone", "distance": 2, "transpositionCostOne": false}}}'
>
> # Handle character transpositions efficiently
> SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedphone", "distance": 1, "transpositionCostOne": true}}}'
>
> # Combine prefix with transposition for robust autocomplete
> SEARCH.QUERY products '{"name": {"$fuzzy": {"value": "haedpho", "prefix": true, "transpositionCostOne": true}}}'
>
> # Multiple words - matches documents containing both terms (with fuzzy tolerance)
> SEARCH.QUERY products '{"name": {"$fuzzy": "wireles headphons"}}'
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.