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

# Fuzzy Search

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

Fuzzy search matches terms that are similar to, but not an exact match for, a query term. Unlike semantic search, which matches terms by meaning using vector embeddings, fuzzy search matches by spelling, using character-level edit distance to catch typos and minor variants.

While Fusion has no single fuzzy search feature, you can combine Solr's native fuzzy matching with Fusion query pipeline stages, choosing an approach based on your search architecture and how much precision you're willing to trade for recall.

<LwTemplate />

## Choose an approach

Depending on your use case and existing pipeline stages, there are several possible approaches to fuzzy search:

<Columns cols={2}>
  <Card icon="wand-magic-sparkles" title="Spell Check stage" href="#spell-check-stage">
    The simplest option. Surfaces "Did you mean?" suggestions when a query returns few results. No custom code required.
  </Card>

  <Card icon="code" title="JavaScript Query stage" href="#javascript-query-stage">
    Rewrites query terms with Solr's fuzzy tilde operator before they reach Solr. Use this to make fuzzy matching automatic for every query.
  </Card>

  <Card icon="sliders" title="Additional Query Parameters stage" href="#field-specific-fuzzy-matching">
    Applies the `{!fuzzy}` query parser to a specific field, such as a product title, without affecting other fields.
  </Card>

  <Card icon="brain" title="Neural Hybrid Search" href="#neural-hybrid-search">
    If you're already running NHS, its semantic vector matching handles most misspelling-like cases without any fuzzy configuration.
  </Card>
</Columns>

| Situation                               | Recommended approach                                                                                      |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| General fuzzy tolerance, minimal setup  | Spell Check stage                                                                                         |
| Catch typos automatically at query time | JavaScript Query stage with `~1`                                                                          |
| Fuzzy matching on one field only        | `{!fuzzy}` via Additional Query Parameters stage                                                          |
| Neural Hybrid Search is enabled         | NHS handles this natively; avoid injecting fuzzy syntax into `q`                                          |
| High-traffic queries with known typos   | Manual [misspelling corrections](/docs/5/fusion/getting-data-out/query-enhancement/misspelling-detection) |

## Spell check stage

Add a [Spell Check query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/spell-check-query-stage) after your Solr Query stage (or Neural Hybrid Query stage) in the query pipeline. It triggers Solr's spell checker when result counts fall below a threshold you configure, and returns spelling suggestions without any custom code.

## JavaScript query stage

Solr supports fuzzy matching natively with the tilde operator: `roam~1` matches terms within an edit distance of 1, such as `foam` or `roams`. Edit distance ranges from 0–2, but start with `1`. An edit distance of `2` expands matching aggressively and can degrade both precision and query performance.

Add a [JavaScript Query stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/javascript-query-stage) before your Solr Query stage to rewrite the `q` parameter:

```javascript theme={"dark"}
function(request, response) {
  var q = request.getFirstParam('q');
  if (!q || q.indexOf('~') !== -1 || q.indexOf('"') !== -1) return;

  var tokens = q.split(/\s+/);
  var fuzzy = tokens.map(function(t) {
    if (t.length >= 4 && t.indexOf(':') === -1 && t[0] !== '+' && t[0] !== '-') {
      return t + '~1';
    }
    return t;
  }).join(' ');

  request.putSingleParam('q', fuzzy);
}
```

<Warning>
  Never apply this to an NHS pipeline. NHS requires `q` to be a raw user query string, not a Solr query parser string. See [Neural Hybrid Search](#neural-hybrid-search).
</Warning>

<Tip>
  Skip terms shorter than 4 characters, terms that already contain an operator (`:`, `+`, `-`), quoted phrases, and terms that are already fuzzy. Don't apply tilde fuzzy to wildcard queries (`*`); the two syntaxes conflict.
</Tip>

For general background on writing and testing pipeline scripts, see [Custom JavaScript Stages for Query Pipelines](/docs/5/fusion/getting-data-out/query-basics/query-pipelines/custom-javascript-query-stages).

## Field-specific fuzzy matching

To apply fuzzy matching to one field only, such as `title_t`, use the `{!fuzzy}` query parser with the [Additional Query Parameters stage](/docs/5/fusion/reference/config-ref/pipeline-stages/query-stages/set-query-params-stage):

```
q={!fuzzy f=title_t maxEdits=1 prefixLength=2 maxExpansions=50}searchterm
```

<ParamField path="maxEdits" type="integer">
  Maximum edit distance, from 0–2. Start with 1.
</ParamField>

<ParamField path="prefixLength" type="integer">
  Number of leading characters that must match exactly. Setting this to 2 or higher significantly reduces the number of terms Solr must evaluate and improves performance.
</ParamField>

<ParamField path="maxExpansions" type="integer">
  Caps how many term variants Solr evaluates per fuzzy term. Lower this value if you see latency spikes.
</ParamField>

<ParamField path="transpositions" type="boolean">
  When `true`, uses Damerau-Levenshtein distance (counts transpositions, such as swapped adjacent letters, as a single edit). When `false`, uses classic Levenshtein distance.
</ParamField>

To rank exact matches first while still surfacing fuzzy matches, keep `q` exact and add the fuzzy expression as a boost query instead: `bq=title_t:searchterm~1`.

## Neural Hybrid Search

Don't inject fuzzy tilde syntax or `{!fuzzy}` local params into the `q` parameter in a Neural Hybrid Search pipeline. NHS requires `q` to be a raw user query string; injecting Solr query parser syntax breaks vectorization. See [Neural Hybrid Search](/docs/5/fusion/hybrid-search/overview).

In an NHS environment:

* Rely on NHS's semantic vector matching, which already handles many misspelling-like cases through embedding proximity.
* Apply fuzzy matching at the Solr request handler level in `solrconfig.xml`, outside the NHS query path, if lexical fuzzy matching is still needed.
* Build a separate lexical-and-fuzzy fallback pipeline that runs only on zero-result queries.

<Note>
  Fusion's [Misspelling Detection](/docs/5/fusion/getting-data-out/query-enhancement/misspelling-detection) feature is deprecated as of Fusion 5.9.15. Lucidworks recommends Neural Hybrid Search as the replacement for spelling tolerance.
</Note>