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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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"}}'
    ```
  </Tab>
</Tabs>