Skip to main content

Handling Typos

Shoppers misspell words. They type blendar when they mean blender, search for half a word while still typing, or write waterproof jacket when the product is named water proof jacket. Typo tolerance makes sure these imperfect queries still find the right products.

Typo tolerance is configured on a search profile and applied at search time. The defaults work well for most stores — you only need to change them when you want stricter or more forgiving behavior, for example exact matching on SKUs or part numbers.

This section breaks typo tolerance into the following sub-sections:

No reindexing required

All settings in this section are applied when a search is executed, not when products are indexed. Changes to a search profile take effect immediately — you do not need to reindex your catalog.

How Typo Tolerance Works​

A "typo" is a single-character mistake in a query word: a wrong character (blendar), a missing character (blnder), an extra character (blennder), or two adjacent characters swapped (lbender). Each of these counts as one typo, measured by Damerau-Levenshtein distance.

Typo tolerance works word by word: each word (token) in the query is corrected independently, and how far a word can be corrected depends on its length and your configuration.

When a search runs, the engine roughly proceeds as follows:

  1. Exact matching: Look for products that match the query as typed.
  2. Typo correction: If there are not enough results (see typo_tokens_threshold), try variations of the query words with up to num_typos corrections, subject to the minimum word length rules.
  3. Compound word handling: Depending on split_join_tokens, also try splitting or joining words (waterproof ↔ water proof).
  4. Word dropping: If there are still not enough results for a multi-word query (see drop_tokens_threshold), drop query words one at a time and search with the rest.

Quick Reference​

All settings live under the typo_tolerance attribute of a search profile, except prefix and the per-field overrides, which are noted below. Every setting is optional; when omitted, the default applies.

SettingWhat it controlsDefault
num_typosMaximum spelling mistakes forgiven per query word (0, 1, or 2)2
fields[].num_typosPer-field override for num_typosprofile value
min_len_to_allow_single_character_correctionMinimum query word length before one typo is forgiven4
min_len_to_allow_two_character_correctionMinimum query word length before two typos are forgiven7
typo_tokens_thresholdTypo correction only runs when exact results are fewer than this (0 = off)1
drop_tokens_thresholdQuery words are dropped when results are fewer than this (0 = off)1
drop_tokens_modeWhich end of the query loses words firstright_to_left
enable_typos_for_numerical_tokensWhether purely numeric words (98765) get typo correctiontrue
enable_typos_for_special_char_tokensWhether words containing special characters (v1.2.10) get typo correctiontrue
split_join_tokensWhether compound and split word forms match each otherfallback
prefix (profile attribute)Whether the last query word can match the beginning of a longer wordtrue
fields[].prefixPer-field override for prefixprofile value

Typo tolerance for synonym resolution is configured separately, under the profile's synonym_settings object — see Allowing Typos When Resolving Synonyms.

Configuring Typo Tolerance​

Set typo_tolerance when creating or updating a search profile:

curl -X POST https://useast.api.elasticpath.com/v2/pcm/catalogs/search-profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "catalog_search_profile",
      "attributes": {
        "slug": "storefront-search",
        "description": "Storefront search with custom typo tolerance",
        "fields": [
          { "name": "name", "weight": 10 },
          { "name": "description", "weight": 5 },
          { "name": "sku", "weight": 8, "num_typos": 0 }
        ],
        "typo_tolerance": {
          "num_typos": 2,
          "min_len_to_allow_single_character_correction": 4,
          "min_len_to_allow_two_character_correction": 7,
          "typo_tokens_threshold": 1,
          "drop_tokens_threshold": 1,
          "drop_tokens_mode": "right_to_left",
          "enable_typos_for_numerical_tokens": true,
          "enable_typos_for_special_char_tokens": false,
          "split_join_tokens": "fallback"
        }
      }
    }
  }'

All typo_tolerance fields are optional — configure only what you want to change. When updating a profile, the typo_tolerance object is replaced as a whole, so include every setting you want to keep. To reset all typo tolerance settings back to the defaults, update the profile with "typo_tolerance": null.

Common Configurations​

These ready-made profiles combine the settings described across this section. Each links to the pages that explain the individual settings in detail.

Forgiving storefront search (default behavior) — two typos on long words, partial matching while typing, compound-word fallback. You do not need to configure anything.

Exact part numbers, forgiving everything else — keep defaults at the profile level and pin down the identifier fields with per-field overrides:

{
  "fields": [
    { "name": "name", "weight": 10 },
    { "name": "description", "weight": 5 },
    { "name": "sku", "weight": 8, "num_typos": 0, "prefix": false }
  ]
}

Strict catalog search — no spelling correction, no partial words, no word dropping:

{
  "prefix": false,
  "typo_tolerance": {
    "typo_tokens_threshold": 0,
    "drop_tokens_threshold": 0,
    "split_join_tokens": "off"
  }
}

Extra-forgiving search for short product names — allow corrections on shorter words and keep searching past exact matches:

{
  "typo_tolerance": {
    "min_len_to_allow_single_character_correction": 3,
    "min_len_to_allow_two_character_correction": 6,
    "typo_tokens_threshold": 3
  }
}
Ask External AI