Welcome to the Meilisearch specifications!

# Settings API

# 1. Summary

This specification describes the global settings API endpoints and cross-reference related sub-resources APIs.

# 2. Motivation

N/A

# 3. Functional Specification

# 3.1. Sub Resource Settings API List

API Resource Description
displayed-attributes displayedAttributes sub-resource API endpoints definition
searchable-attributes searchableAttributes sub-resource API endpoints definition
filterable-attributes filterableAttributes sub-resource API endpoints definition
sortable-attributes sortableAttributes sub-resource API endpoints definition
ranking-rules rankingRules sub-resource API endpoints definition
stop-words stopWords sub-resource API endpoints definition
separator-tokens separatorTokens sub-resource API endpoints definition
non-separator-tokens nonSeparatorTokens sub-resource API endpoints definition
dictionary dictionary sub-resource API endpoints definition
synonyms synonyms sub-resource API endpoints definition
distinct-attribute distinctAttribute sub-resource API endpoints definition
typo-tolerance typoTolerance sub-resource API endpoints definition
pagination pagination sub-resource API endpoints definition
faceting faceting sub-resource API endpoints definition
faceting proximityPrecision sub-resource API endpoints definition

Each setting is exposed as a sub-resource of the indexes/:index_uid/settings endpoints. e.g. The ranking rules setting of a Meilisearch index is exposed at indexes/:index_uid/settings/ranking-rules.

Some setting changes cause a complete re-indexing of the documents. See 4.1. Triggering Documents Re-indexing.

# 3.2. API Endpoints Definition

Manipulate all settings of a Meilisearch index.

# 3.2.1. GET - indexes/:index_uid/settings

Fetch the settings of a Meilisearch index.

# 3.2.1.1. Response Definition
Field Type Required
displayedAttributes Array of String true
searchableAttributes Array of String true
filterableAttributes Array of String true
sortableAttributes Array of String true
rankingRules Array of String true
stopWords Array of String true
separatorTokens Array of String true
nonSeparatorTokens Array of String true
dictionary Array of String true
synonyms Object true
distinctAttribute String / null true
typoTolerance Object true
pagination Object true
faceting Object true
proximityPrecision String true

The attributes ordering in the response payload is equivalent to the order described in the table above.

# 3.2.1.2. Errors
  • 🔴 If the requested index_uid does not exist, the API returns an index_not_found error.

# 3.2.2. PATCH - indexes/:index_uid/settings

Modify the settings of a Meilisearch index.

# 3.2.2.1. Request Payload Definition
Field Type Required
displayedAttributes Array of String / null false
searchableAttributes Array of String / null false
filterableAttributes Array of String / null false
sortableAttributes Array of String / null false
rankingRules Array of String / null false
stopWords Array of String / null false
separatorTokens Array of String / null false
nonSeparatorTokens Array of String / null false
dictionary Array of String / null false
synonyms Object / null false
distinctAttribute String / null false
typoTolerance Object / null false
pagination Object / null false
faceting Object / null false
proximityPrecision String / null false
  • The request payload accepts partial definitions, the value of missing fields will remain unchanged.
  • The request payload accepts the null value for any setting, which will reset the setting to its default value.
# 3.2.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.2.2.3. Errors

Errors related to a sub-resource are described in its respective specification. See 3.1. Sub Resource Settings API List.

# 3.2.2.3.1. Async Errors

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

# 3.2.2.4. Lazy Index Creation

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

# 3.2.3. DELETE - indexes/:index_uid/settings

Reset the settings of a Meilisearch index to the default values.

# 3.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.3.2. Default Values

See 3.1. Sub Settings API Resource List to get the default values of each setting.

# 3.2.3.3. Errors
  • 🔴 Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.

Errors related to a sub-resource are described in its respective specification. See 3.1. Sub Resource Settings API List.

# 3.2.3.3.1. Asynchronous Index Not Found Error

# 3.2.4. General Errors

These errors apply to all endpoints described here.

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

Changing any of the following index settings will cause documents to be re-indexed:

  • searchableAttributes
  • filterableAttributes
  • sortableAttributes
  • distinctAttribute
  • stopWords
  • separatorTokens
  • nonSeparatorTokens
  • dictionary
  • proximityPrecision

# 5. Future Possibilities

n/a

← Sortable attributes setting api →