Welcome to the Meilisearch specifications!

# Typo Tolerance Settings API

# 1. Summary

This specification describes the customizable options for the typo tolerance settings.

# 2. Motivation

Tolerance to typos is critical when building an enjoyable search experience. Meilisearch ranks typo-free matched documents above others based on the default settings that we believe are best for most users.

Meilisearch can adapt to different use-cases by providing customization options for the typo tolerance feature.

# 3. Functional Specification

# 3.1. typoTolerance API resource definition

Field Type Required
enabled Boolean False
disableOnAttributes Array of String False
disableOnWords Array of String False
minWordSizeForTypos Object False

# 3.1.1. enabled

  • Type: Boolean
  • Required: False
  • Default: true

Whether the typo tolerance feature is enabled.

# 3.1.1.1. Impacts on the typo ranking rule

The presence of typo in the ranking rules setting does not influence the activation/deactivation of the typo tolerance feature.

If the rankingRules parameter of the index settings does not contain the typo rule, the results are not sorted according to the number of typos found.

The typo tolerance feature is still used to match documents.

# 3.1.2. disableOnAttributes

  • Type: Array of String
  • Required: False
  • Default: []

disableOnAttributes disable the typo tolerance feature on the specified attributes list.

Any attributes defined in disableOnAttributes won't have their values matched by the typo tolerance.

# 3.1.2.1. Example

Given ["title"] as disableOnAttributes and the following document

{
    "id": 0,
    "title": "Hey World"
}

The engine won't try to match query term with typos with values of the title attribute at search time to match documents.

  • Typing Warld won't bring the document as a candidate for the search results.

# 3.1.3. disableOnWords

  • Type: Array of String
  • Required: False
  • Default: []

disableOnWords disable the typo tolerance feature on a list of search query terms.

This field is case insensitive since the document attributes values are lowercased and de-unicoded internally.

# 3.1.3.1. Example

If Javascript is specified in disableOnWords, the engine won't apply the typo tolerance on the query term Javascript or javascript if typed at search time to match documents.

# 3.1.4. minWordSizeForTypos

  • Type: Object
  • Required: False

# 3.1.4.1. minWordSizeForTypos Object Definition

Field Type Required
oneTypo Integer False
twoTypos Integer False

# 3.1.4.2. oneTypo

  • Type: Integer
  • Required: False
  • Default: 5

oneTypo customize the minimum size for a word to tolerate 1 typo.

Given the default value 5, the search engine starts to apply typo tolerance on a query term if its length is at least equal to 5 characters.

See 2.1. Typos calculation section

# 3.1.4.2.1 Example

Given 5 as oneTypo and the following document

{
    "id": 0,
    "title": "Hey World"
}
  • Typing World with 1 typo, e.g. Warld will match World. It accepts 1 typo since World size is made of 5 chars.
  • Typing Hey with 1 typo, e.g. Hoy won't match Hey. It accepts 0 typo since Hey size is made of 3 chars.

# 3.1.4.3. twoTypos

  • Type: Integer
  • Required: False
  • Default: 9

twoTypos customize the minimum size for a word to tolerate 2 typos.

Given the default value 9, the search engine handles up to 2 typos on a query term if its length is at least equal to 9 characters.

See 2.1. Typos calculation section

# 3.1.4.3.1. Example

Given 3 for oneTypo and 5 as twoTypos and the following document

{
    "id": 0,
    "title": "Hey World"
}
  • Typing World with 2 typos, e.g. Warrld will match World. It accepts up to 2 typos since World size is made of 5 chars.
  • Typing Hey with 1 typo, e.g. Hoy will match Hey. It accepts only 1 typo since Hey size is made of 3 chars.

# 3.2. API Endpoints Definition

# 3.2.1. Global Settings API Endpoints Definition

typoTolerance is a sub-resource of /indexes/:index_uid/settings.

See Settings API.

# 3.2.2. indexes/:index_uid/settings/typo-tolerance

Manage the typo tolerance configuration for an index.

# 3.2.2.1. GET - indexes/:index_uid/settings/typo-tolerance

Allow fetching the current definition of the typo tolerance feature for an index.

200 - Response body

    {
        "enabled": true,
        "disableOnAttributes": [],
        "disableOnWords": [],
        "minWordSizeForTypos": {
            "oneTypo": 5,
            "twoTypos": 9
        }
    }

All properties must be returned when the resource is retrieved.

# 3.2.2.1.2. Errors
  • 🔴 Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.
  • 🔴 If the index does not exist, the API returns an index_not_found error.

# 3.2.2.2. PATCH - indexes/:index_uid/settings/typo-tolerance

Allow customizing partially the settings of the typo tolerance feature for an index.

Request payload

{
    "disableOnAttributes": [
        "title",
        "description"
    ],
    "minWordSizeForTypos": 4
}

202 Accepted - Example Response

{
    "uid": 42,
    "indexUid": "books",
    "status": "enqueued",
    "type": "settingsUpdate",
    "enqueuedAt": "2022-03-01T18:39:29.228155Z"
}
# 3.2.2.2.1. Response Definition

When the request is successful, Meilisearch returns the HTTP code 202 Accepted. The response's content is the summarized representation of the received asynchronous task.

See Summarized task Object for 202 Accepted.

# 3.2.2.2.2. Errors
# 3.2.2.2.2.1. Async Errors

Otherwise, Meilisearch will create the index in a lazy way. See 3.2.2.2.3. Lazy Index Creation.

  • 🔴 When sending invalid values with either oneTypo OR twoTypos being specified for the minWordSizeForTypos object fields returns an invalid_settings_typo_tolerance error.
# 3.2.2.2.3. Lazy Index Creation

If the requested index_uid does not exist, and the authorization layer allows it (See 3.2.2.2.2.1. Async Errors), Meilisearch will create the index when the related asynchronous task resource is executed. See 3.2.2.2.1. Response Definition.

# 3.2.2.3. DELETE- indexes/:index_uid/settings/typo-tolerance

Allow resetting the typo tolerance feature to the default for an index.

# 3.2.2.3.1. Response Definition

When the request is in a successful state, Meilisearch returns the HTTP code 202 Accepted. The response's content is the summarized representation of the received asynchronous task.

See Summarized task Object for 202 Accepted.

# 3.2.2.3.2. Errors
  • 🔴 Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.
# 3.2.2.3.2.1. Asynchronous Index Not Found Error

# 3.2.3. General Errors

These errors apply to all endpoints described here.

# 3.2.3.1. Auth Errors

The auth layer can return the following errors if Meilisearch is secured (a master-key is defined).

  • 🔴 Accessing this route without the Authorization header returns a missing_authorization_header error.
  • 🔴 Accessing this route with a key that does not have permissions (i.e. other than the master-key) returns an invalid_api_key error.

# 2. Technical Details

# 2.1. Typos Calculation

The size of a query term triggers the typo tolerance feature.

By default, a query term made of 5 characters can tolerate 1 typo, while a query term made of 9 characters can tolerate 2 typos.

If a query term can be derived from a distance of one or two typos to be found in a document, it will be selected as a candidate. The number of typos found has an impact on the relevancy.

# 2.1.1 Typo On The First Character

A query term having the first character considered as a typo will not count as 1 typo but as 2 typos.

It permits to drastically reduce the search space in this case, thus speed-up the search response.

# 2.1.2. Clamping Typo On Concatened Query Terms

The concatenation of two query terms is equal to 1 typo.

e.g. If Le tableau is typed, the concatened string Letableau made of 9 letters can only have 1 typo instead of 2 since 1 typo is already counted by the concatenation.

# 2.2. Typo Ranking Rule

The typo ranking rule favors candidates with the least typos. That is, if a document is found with two typos, it will be ranked as less important than a document found with 1 typo. 0 typo is the most favorable case.

# 3. Future Possibilities

  • Expose typoTolerance resource as a search parameter to override index settings.
  • Add the possibility to disable the typo tolerance feature on all numeric fields.
  • Add different modes of result matching for the typo feature. e.g. default/min/strict
  • Introduce synchronous invalid_settings_typo_tolerance_{fieldName} error code granularity.

← Search api →