Correcting Misspelled Words

The settings on this page control the core of typo tolerance: how many spelling mistakes are forgiven in each query word, how long a word must be before it is corrected, when correction runs at all, and which kinds of words (numbers, product codes, synonyms) are eligible. These configurations work together — the interactions at the end of the page summarize how they combine.

All settings here live under the typo_tolerance attribute of a search profile and are applied at search time — no reindexing required.

Maximum Number of Typos (num_typos)

num_typos sets how many spelling mistakes are forgiven in each query word: 0 (exact match only), 1, or 2 (default).

Consider a product named blender, a query blendar with one mistake, and a query blandar with two mistakes:

num_typos	Search for blendar (one mistake)	Search for blandar (two mistakes)
0	No results	No results
1	Finds blender	No results
2	Finds blender	Finds blender

{ "typo_tolerance": { "num_typos": 1 } }

num_typos is an upper bound, not a guarantee

The number of corrections actually applied to a word is also capped by its length — see Minimum Word Lengths for Correction. Short words receive fewer corrections than num_typos allows, or none at all.

Per-Field Overrides

Each entry in the profile's fields array accepts its own num_typos, which overrides the profile-level value for that field only. This is the recommended way to keep identifiers precise while product names stay forgiving.

For example, take two products — one named Wrench and another whose SKU is wrench — and the misspelled query wronch:

Configuration	Search for wronch matches
Profile num_typos: 2, no per-field override	Both products (via name and via sku)
Profile num_typos: 2, sku field num_typos: 0	Only the product named wrench (via name)

{
  "fields": [
    { "name": "name", "weight": 10 },
    { "name": "sku", "weight": 5, "num_typos": 0 }
  ],
  "typo_tolerance": { "num_typos": 2 }
}

Fields without an override inherit the profile-level num_typos, and a profile without a value uses the default of num_typos: 2.

Minimum Word Lengths for Correction

Correcting very short words causes false matches — forgiving one typo in a three-letter word like cat would match car, can, hat, and more. Two settings protect against this by requiring a minimum query word length before corrections are attempted:

• min_len_to_allow_single_character_correction (default 4): words shorter than this get no typo correction at all.
• min_len_to_allow_two_character_correction (default 7): words shorter than this get at most one correction, even when num_typos is 2.

These length rules always apply on top of num_typos — the corrections applied to a word are the smaller of num_typos and what the word's length permits. With the defaults:

Query word length	Corrections allowed (with num_typos: 2)
1–3 characters	None — must match exactly
4–6 characters	At most 1
7+ characters	Up to 2

Worked examples:

• The 4-character query cawd is corrected to card with the default minimum of 4. Raise min_len_to_allow_single_character_correction to 5 and the same query finds nothing.
• The 7-character query monetar (two mistakes) is corrected to monitor with the default minimum of 7. Raise min_len_to_allow_two_character_correction to 8 and the same query finds nothing.

{
  "typo_tolerance": {
    "min_len_to_allow_single_character_correction": 5,
    "min_len_to_allow_two_character_correction": 8
  }
}

note

min_len_to_allow_two_character_correction must be greater than or equal to min_len_to_allow_single_character_correction.

When Typo Correction Kicks In (typo_tokens_threshold)

Typo-corrected variations of the query are only generated when the number of exactly matching results is fewer than typo_tokens_threshold (default 1). In other words, with the default, typo correction only runs when the query as typed finds nothing. This can be useful if there is a requirement to always find a certain number of products, e.g., always show at least ten products to the users even if the query does not match ten products.

Raising the threshold tells the engine to keep looking for typo-corrected matches even when exact results exist. Consider two products, lantern and one named lantirn (one character apart), and the query lantern:

typo_tokens_threshold	Search for lantern matches
1 (default)	Only lantern — one exact result exists, so no typo variations are tried
2	lantern and lantirn — one exact result is fewer than 2, so typo variations are tried

{ "typo_tolerance": { "typo_tokens_threshold": 2 } }

Turning Typo Tolerance Off

Setting typo_tokens_threshold to 0 disables typo tolerance entirely for the profile — every query word must match exactly:

{ "typo_tolerance": { "typo_tokens_threshold": 0 } }

With this setting, a query like compbss no longer finds compass, regardless of num_typos. This is useful for fields where exact matches are required e.g., SKUs, part numbers, etc.

Typo Tolerance for Numbers (enable_typos_for_numerical_tokens)

When enable_typos_for_numerical_tokens is false, query words made up entirely of digits must match exactly. This prevents a search for one model number from matching another that happens to be one digit apart.

Consider a product named sensor 98765 and the query 98760 (one digit off):

enable_typos_for_numerical_tokens	Search for 98760 matches
true (default)	sensor 98765
false	Nothing

{ "typo_tolerance": { "enable_typos_for_numerical_tokens": false } }

Typo Tolerance for Product Codes (enable_typos_for_special_char_tokens)

When enable_typos_for_special_char_tokens is false, any query word containing at least one special character (anything outside a-z, A-Z, 0-9) must match exactly. This keeps hyphenated part numbers, version strings, and similar codes precise.

With the setting disabled and num_typos: 2, one-character-off queries against these products find nothing:

Product name	One-mistake query	true (default)	false
abc-def	abx-def	Found	Nothing
abc-123	abc-124	Found	Nothing
123-456	123-457	Found	Nothing
v1.2.0	v1.2.1	Found	Nothing

{ "typo_tolerance": { "enable_typos_for_special_char_tokens": false } }

Two things to keep in mind:

• Plain alphanumeric words are unaffected. A word like abc123 or kilo404 contains no special character, so it keeps regular typo tolerance either way.
• The special character must be indexed. By default, the search index strips special characters (v1.2.0 is indexed as v120), so the word no longer qualifies as a special-character token. Add the character to symbols_to_index on the relevant field for this setting to apply — see Customizing Tokenization.

Typos in Synonyms

Typo tolerance can also be extended to synonym resolution so that a misspelled query word still triggers its synonym expansion. See Allowing Typos When Resolving Synonyms in the synonyms guide.

How These Settings Work Together

The correction settings on this page combine as limits on a single process:

• num_typos and the length minimums combine as limits. The corrections applied to a word are the smaller of num_typos and what the word's length permits. Setting num_typos: 2 does not correct two mistakes in a 5-character word unless you also lower min_len_to_allow_two_character_correction.
• typo_tokens_threshold gates everything. typo_tokens_threshold: 0 switches typo correction off no matter what num_typos says.
• Per-field values beat profile values. fields[].num_typos overrides the profile-level typo_tolerance.num_typos for that field only.
• Token classification depends on indexing. enable_typos_for_special_char_tokens only recognizes a word as a special-character token when the special character is preserved in the index via symbols_to_index.
• Synonym typo tolerance is separate. number_of_typos_allowed_when_resolving_synonyms (under synonym_settings) only affects synonym expansion. It does not affect the regular typo tolerance process and is not affected by other settings like num_typos and typo_tokens_threshold.

Related Resources

• Handling Typos
• Compound Words
• Dropping Words From Multi-Word Queries
• Using Synonyms