Welcome to the Meilisearch specifications!

# Dictionary Setting API

# 1. Summary

This specification describes the dictionary index setting API endpoints.

# 2. Motivation

N/A

# 3. Functional Specification

# 3.1. Explanations

The dictionary index setting allows the configuration of a list of words for which the segmentation is overriden in search queries and indexing. The dictionary's words contained in a search query will be segmented as defined in the dictionary.

# 3.1.1. Usage Example

Suppose a database contains books with authors. Some athors contains separators in their names like J. R. R. Tolkien or J. K. Rowling. To set J. R. R. and J. K. words in the dictionary, it can be specified the following way.

Request payload PUT- /indexes/articles/settings/dictionary

["J. R. R.", "J. K."]

By adding authors' names as J. R. R. and J. K. to the dictionary, Meilisearch considers them as unique words instead of splitting them into several parts.

# 3.2. Global Settings API Endpoints Definition

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

See Settings API.

# 3.3. API Endpoints Definition

Manipulate the dictionary setting of a Meilisearch index.

# 3.3.1. GET - indexes/:index_uid/settings/dictionary

Fetch the dictionary setting of a Meilisearch index.

# 3.3.1.1. Response Definition
  • Type: Array of String
  • Default: []
# 3.3.1.2. Errors
  • 🔴 Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.
  • 🔴 If the requested index_uid does not exist, the API returns an index_not_found error.

# 3.3.2. PUT - indexes/:index_uid/settings/dictionary

Modify the dictionary setting of a Meilisearch index.

# 3.3.2.1. Request Payload Definition
  • Type: Array of String / null

Setting null is equivalent to using the 3.3.3. DELETE - indexes/:index_uid/settings/dictionary API endpoint.

# 3.3.2.2. 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.3.2.3. Errors
# 3.3.2.3.1. Async Errors

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

# 3.3.2.4. Lazy Index Creation

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

# 3.3.3. DELETE - indexes/:index_uid/settings/dictionary

Reset the dictionary setting of a Meilisearch index to the default value [].

# 3.3.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.3.3.3. Errors
  • 🔴 Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.
# 3.3.3.3.1. Asynchronous Index Not Found Error

# 3.3.4. General Errors

These errors apply to all endpoints described here.

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

# 4. Technical Details

# 4.1. Triggering Documents Re-Indexing

Meilisearch favors search speed and makes a trade-off on indexing speed by computing internal data structures to get search results as fast as possible.

Modifying this index setting causes documents to be re-indexed.

# 5. Future Possibilities

In the future we could allow the user to provide a custom normalization for the words contained in the dictionary by allowing to pass an object instead of an array:

{
    "J. R. R.": "jrr",
    "J.R.R.": "jrr",
    "J. K.": "jk"
    "J.K.": "jk"
}

Or by providing a new settings to do it.

← Documents api →