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

# Smart Matching

When you provide a value directly to a field (without explicit operators like `$phrase` or `$fuzzy`),
the search engine applies smart matching. The behavior depends on the field type:

* **Numeric, boolean, and date fields**: Smart matching performs an exact equality check.
* **Text fields**: Smart matching applies intelligent matching strategies to find the most relevant results, as described below.

### Text Field Matching

For text fields, the matching behavior varies based on the input format.

### Single-Word Values

For single-word searches, the engine runs multiple matching strategies and combines their scores:

1. **Exact term match** (high boost): Documents containing the exact token score highest.

2. **Fuzzy match** (no boost): Documents containing terms within Levenshtein distance 1
   (with transpositions counting as a single edit) are included.

3. **Fuzzy prefix match** (no boost): Documents containing terms that start with a fuzzy
   variation of the search term are included. This handles incomplete words during typing.

```
{ name: "tabletop" }
```

This query returns results in roughly this order:

* "**tabletop**" (exact match)
* "**tabeltop**" (fuzzy match, 1 edit away)
* "**tabeltopping**" (fuzzy prefix match, incomplete word with typos matches full term)

### Multi-Word Values

For multi-word searches, the engine runs multiple matching strategies simultaneously and combines
their scores to surface the most relevant results:

1. **Exact phrase match** (highest boost): Documents where all words appear adjacent and in order
   score highest. Searching for `wireless headphones` ranks documents containing
   "wireless headphones" as a phrase above those with the words scattered.

2. **Exact phrase match with slop** (medium boost): Documents where all the query terms appear in
   order but not necessarily adjacent, allowing for a small number of intervening words—receive a boost.
   Searching for wireless headphones would rank documents containing `wireless bluetooth headphones`
   above those where the words are far apart, but below an exact phrase match (`wireless headphones`).

3. **Terms match** (medium boost): Documents containing all or some of the search terms, regardless of
   position or order, receive a moderate score boost.

4. **Fuzzy matching** (no boost): Documents containing terms similar to the search terms
   (accounting for typos) are included with a lower score.

5. **Fuzzy prefix on last word** (no boost): The last word is also matched with fuzzy prefix,
   handling incomplete words during search-as-you-type scenarios.

```
{ description: "wireless headphon" }
```

This query returns results in roughly this order:

* "Premium **wireless headphones** with noise cancellation" (phrase match with fuzzy prefix on last word)
* "**Headphones** with **wireless** connectivity" (all terms present, different order)
* "**Wireles headphone** with long battery" (fuzzy match for typos)

### Double-Quoted Phrases

Wrapping your search value in double quotes forces exact phrase matching.
The words must appear adjacent and in the exact order specified.

```
{ description: "\"noise cancelling\"" }
```

This matches only documents containing "noise cancelling" as an exact phrase.
It will NOT match:

* "noise and cancelling" (words not adjacent)
* "cancelling noise" (wrong order)
* "noise-cancelling" (hyphenated, tokenized differently)

This is useful when you need precise matching without the fuzzy tolerance of smart matching.

### The `$smart` Operator

Smart matching is applied implicitly when you provide a plain value to a field. You can also invoke it explicitly using the `$smart` operator. The behavior is identical — `$smart` is useful when you want to be more explicit about your intent, or when you need to combine smart matching with other operators like [`$boost`](./boost).

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    // Explicit smart matching
    await index.query({
      filter: { name: { $smart: "wireless headphones" } },
    });

    // Combine smart matching with $boost
    await index.query({
      filter: {
        $and: [
          { name: { $smart: "wireless headphones", $boost: 2.0 } },
          { description: { $smart: "noise cancelling" } },
        ],
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Explicit smart matching
    index.query(filter={"name": {"$smart": "wireless headphones"}})

    # Combine smart matching with $boost
    index.query(filter={
        "$and": [
            {"name": {"$smart": "wireless headphones", "$boost": 2.0}},
            {"description": {"$smart": "noise cancelling"}},
        ],
    })
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    # Explicit smart matching
    SEARCH.QUERY products '{"name": {"$smart": "wireless headphones"}}'

    # Combine smart matching with $boost
    SEARCH.QUERY products '{"$and": [{"name": {"$smart": "wireless headphones", "$boost": 2.0}}, {"description": {"$smart": "noise cancelling"}}]}'
    ```
  </Tab>
</Tabs>

### When to Use Explicit Operators

Smart matching works well for general search scenarios, but consider using explicit operators when you need:

* **Typo tolerance only**: Use [`$fuzzy`](./fuzzy) with specific distance settings
* **Phrase with gaps**: Use [`$phrase`](./phrase) with the `slop` parameter
* **Pattern matching**: Use [`$regex`](./regex) for regular expression patterns