Settings

Use the /settings route to customize search settings for a given index. You can either modify all index settings at once using the update settings endpoint, or use a child route to configure a single setting.

For a conceptual overview of index settings, refer to the indexes explanation. To learn more about the basics of index configuration, refer to the index configuration tutorial.

Meilisearch Cloud offers a user-friendly graphical interface for managing index settings in addition to the /settings route. The Cloud interface offers more immediate and visible feedback, and is helpful for tweaking relevancy when used in conjunction with the search preview.

By default, the settings object looks like this. All fields are modifiable.

{
  "displayedAttributes": [
    "*"
  ],
  "searchableAttributes": [
    "*"
  ],
  "filterableAttributes": [],
  "sortableAttributes": [],
  "rankingRules":
  [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness"
  ],
  "stopWords": [],
  "nonSeparatorTokens": [],
  "separatorTokens": [],
  "dictionary": [],
  "synonyms": {},
  "distinctAttribute": null,
  "typoTolerance": {
    "enabled": true,
    "minWordSizeForTypos": {
      "oneTypo": 5,
      "twoTypos": 9
    },
    "disableOnWords": [],
    "disableOnAttributes": []
  },
  "faceting": {
    "maxValuesPerFacet": 100
  },
  "pagination": {
    "maxTotalHits": 1000
  },
  "proximityPrecision": "byWord",
  "searchCutoffMs": null
}

This route allows you to retrieve, configure, or reset all of an index's settings at once.

Get the settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings'

{
  "displayedAttributes": [
    "*"
  ],
  "searchableAttributes": [
    "*"
  ],
  "filterableAttributes": [],
  "sortableAttributes": [],
  "rankingRules":
  [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness"
  ],
  "stopWords": [],
  "nonSeparatorTokens": [],
  "separatorTokens": [],
  "dictionary": [],
  "synonyms": {},
  "distinctAttribute": null,
  "typoTolerance": {
    "enabled": true,
    "minWordSizeForTypos": {
      "oneTypo": 5,
      "twoTypos": 9
    },
    "disableOnWords": [],
    "disableOnAttributes": []
  },
  "faceting": {
    "maxValuesPerFacet": 100
  },
  "pagination": {
    "maxTotalHits": 1000
  },
  "proximityPrecision": "byWord",
  "searchCutoffMs": null
}

Update the settings of an index.

Passing null to an index setting will reset it to its default value.

Updates in the settings route are partial. This means that any parameters not provided in the body will be left unchanged.

If the provided index does not exist, it will be created.

curl \
  -X PATCH 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "rankingRules": [
      "words",
      "typo",
      "proximity",
      "attribute",
      "sort",
      "exactness",
      "release_date:desc",
      "rank:desc"
    ],
    "distinctAttribute": "movie_id",
    "searchableAttributes": [
      "title",
      "overview",
      "genres"
    ],
    "displayedAttributes": [
      "title",
      "overview",
      "genres",
      "release_date"
    ],
    "stopWords": [
      "the",
      "a",
      "an"
    ],
    "sortableAttributes": [
      "title",
      "release_date"
    ],
    "synonyms": {
      "wolverine": [
        "xmen",
        "logan"
    ],
      "logan": ["wolverine"]
    },
    "typoTolerance": {
      "minWordSizeForTypos": {
        "oneTypo": 8,
        "twoTypos": 10
      },
      "disableOnAttributes": ["title"]
    },
    "pagination": {
      "maxTotalHits": 5000
    },
    "faceting": {
      "maxValuesPerFacet": 200
    },
    "searchCutoffMs": 150
  }'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset all the settings of an index to their default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Allows users to instruct Meilisearch to consider groups of strings as a single term by adding a supplementary dictionary of user-defined terms.

This is particularly useful when working with datasets containing many domain-specific words, and in languages where words are not separated by whitespace such as Japanese.

Custom dictionaries are also useful in a few use-cases for space-separated languages, such as datasets with names such as "J. R. R. Tolkien" and "W. E. B. Du Bois".

"dictionary": ["W. E. B.", "W.E.B."],
"synonyms": {
  "W. E. B.": ["W.E.B."],
  "W.E.B.": ["W. E. B."]
}

Get an index's user-defined dictionary.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/dictionary'

[]

Update an index's user-defined dictionary.

["J. R. R.", "W. E. B."]

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings/dictionary' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "J. R. R.",
    "W. E. B."
  ]'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-09-11T15:39:06.073314Z"
}

Use the returned taskUid to get more details on the status of the task.

Reset an index's dictionary to its default value, [].

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/dictionary'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

Use the returned taskUid to get more details on the status of the task.

The attributes added to the displayedAttributes list appear in search results. displayedAttributes only affects the search endpoints. It has no impact on the get documents with POST and get documents with GET endpoints.

By default, the displayedAttributes array is equal to all fields in your dataset. This behavior is represented by the value ["*"].

To learn more about displayed attributes, refer to our dedicated guide.

Get the displayed attributes of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/displayed-attributes'

[
  "title",
  "overview",
  "genres",
  "release_date.year"
]

Update the displayed attributes of an index.

[<String>, <String>, …]

An array of strings. Each string should be an attribute that exists in the selected index.

If an attribute contains an object, you can use dot notation to specify one or more of its keys, for example, "displayedAttributes": ["release_date.year"].

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "title",
    "overview",
    "genres",
    "release_date"
  ]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the displayed attributes of the index to the default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/displayed-attributes'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

The distinct attribute is a field whose value will always be unique in the returned documents.

To learn more about the distinct attribute, refer to our dedicated guide.

Get the distinct attribute of an index.

curl \
  -X GET 'http://localhost:7700/indexes/shoes/settings/distinct-attribute'

"skuid"

Update the distinct attribute field of an index.

<String>

A string. The string should be an attribute that exists in the selected index.

If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting, for example, "distinctAttribute": "product.skuid".

To learn more about the distinct attribute, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/shoes/settings/distinct-attribute' \
  -H 'Content-Type: application/json' \
  --data-binary '"skuid"'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the distinct attribute of an index to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/shoes/settings/distinct-attribute'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

With Meilisearch, you can create faceted search interfaces. This setting allows you to:

• Define the maximum number of values returned by the facets search parameter
• Sort facet values by value count or alphanumeric order

To learn more about faceting, refer to our dedicated guide.

Get the faceting settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/faceting'

{
  "maxValuesPerFacet": 100,
  "sortFacetValuesBy": {
    "*": "alpha"
  }
}

Partially update the faceting settings for an index. Any parameters not provided in the body will be left unchanged.

{
  "maxValuesPerFacet": <Integer>,
  "sortFacetValuesBy":{
      <String>: "count",
      <String>: "alpha"
  }
}

Suppose a query's search results contain a total of three values for a colors facet: blue, green, and red. If you set maxValuesPerFacet to 2, Meilisearch will only return blue and green in the response body's facetDistribution object.

The following code sample sets maxValuesPerFacet to 2, sorts the genres facet by descending count, and all other facets in ascending alphanumeric order:

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxValuesPerFacet": 2,
    "sortFacetValuesBy": {
      "*": "alpha",
      "genres": "count"
    }
  }'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

You can use the returned taskUid to get more details on the status of the task.

Reset an index's faceting settings to their default value. Setting sortFacetValuesBy to null(--data-binary '{ "sortFacetValuesBy": null }'), will restore it to the default value ("*": "alpha").

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/faceting'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

You can use the returned taskUid to get more details on the status of the task.

Attributes in the filterableAttributes list can be used as filters or facets.

To learn more about filterable attributes, refer to our dedicated guide.

Get the filterable attributes for an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/filterable-attributes'

[
  "genres",
  "director",
  "release_date.year"
]

Update an index's filterable attributes list.

[<String>, <String>, …]

An array of strings containing the attributes that can be used as filters at query time.

If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: "filterableAttributes": ["release_date.year"].

To learn more about filterable attributes, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "genres",
    "director"
  ]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset an index's filterable attributes list back to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/filterable-attributes'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

By default, Meilisearch auto-detects the languages used in your documents. This setting allows you to explicitly define which languages are present in a dataset, and in which fields.

Localized attributes affect searchableAttributes, filterableAttributes, and sortableAttributes.

Configuring multiple languages for a single index may negatively impact performance.

localizedAttributes must be an array of locale objects. Its default value is [].

Locale objects must have the following fields:

Meilisearch supports the following ISO-639-3 three-letter locales: epo, eng, rus, cmn, spa, por, ita, ben, fra, deu, ukr, kat, ara, hin, jpn, heb, yid, pol, amh, jav, kor, nob, dan, swe, fin, tur, nld, hun, ces, ell, bul, bel, mar, kan, ron, slv, hrv, srp, mkd, lit, lav, est, tam, vie, urd, tha, guj, uzb, pan, aze, ind, tel, pes, mal, ori, mya, nep, sin, khm, tuk, aka, zul, sna, afr, lat, slk, cat, tgl, hye.

You may alternatively use ISO-639-1 two-letter equivalents to the supported locales.

You may also assign an empty array to locales. In this case, Meilisearch will auto-detect the language of the associated attributePatterns.

Attribute patterns may begin or end with a * wildcard to match multiple fields: en_*, *-ar.

You may also set attributePatterns to *, in which case Meilisearch will treat all fields as if they were in the associated locale.

Get the localized attributes settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/localized-attributes'

{
  "localizedAttributes": [
    {"locales": ["jpn"], "attributePatterns": ["*_ja"]}
  ]
}

Update the localized attributes settings of an index.

{
  "localizedAttributes": [
    {
     "locale": [<String>, …],
     "attributePatterns": [<String>, …],
    }
  ]
}

{
  "taskUid": 1,
  "indexUid": "INDEX_NAME",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

You can use the returned taskUid to get more details on the status of the task.

Reset an index's localized attributes to their default value.

{
  "taskUid": 1,
  "indexUid": "INDEX_NAME",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

You can use the returned taskUid to get more details on the status of the task.

To protect your database from malicious scraping, Meilisearch has a default limit of 1000 results per search. This setting allows you to configure the maximum number of results returned per search.

maxTotalHits takes priority over search parameters such as limit, offset, hitsPerPage, and page.

For example, if you set maxTotalHits to 100, you will not be able to access search results beyond 100 no matter the value configured for offset.

To learn more about paginating search results with Meilisearch, refer to our dedicated guide.

Get the pagination settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/pagination'

{
  "maxTotalHits": 1000
}

Partially update the pagination settings for an index.

{maxTotalHits: <Integer>}

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxTotalHits": 100
  }'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

You can use the returned taskUid to get more details on the status of the task.

Reset an index's pagination settings to their default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/pagination'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

You can use the returned taskUid to get more details on the status of the task.

Calculating the distance between words is a resource-intensive operation. Lowering the precision of this operation may significantly improve performance and will have little impact on result relevancy in most use-cases. Meilisearch uses word distance when ranking results according to proximity and when users perform phrase searches.

proximityPrecision accepts one of the following string values:

• "byWord": calculate the precise distance between query terms. Higher precision, but may lead to longer indexing time. This is the default setting
• "byAttribute": determine if multiple query terms are present in the same attribute. Lower precision, but shorter indexing time

Get the proximity precision settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/proximity-precision'

{
  "proximityPrecision": "byWord"
}

Update the pagination settings for an index.

"byWord"|"byAttribute"

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings/proximity-precision' \
  -H 'Content-Type: application/json' \
  --data-binary '"byAttribute"'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-04-14T15:50:29.821044Z"
}

You can use the returned taskUid to get more details on the status of the task.

Reset an index's proximity precision setting to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-04-14T15:51:47.821044Z"
}

You can use the returned taskUid to get more details on the status of the task.

Ranking rules are built-in rules that rank search results according to certain criteria. They are applied in the same order in which they appear in the rankingRules array.

To learn more about ranking rules, refer to our dedicated guide.

[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness"
]

Get the ranking rules of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/ranking-rules'

[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  "release_date:desc"
]

Update the ranking rules of an index.

[<String>, <String>, …]

An array that contains ranking rules in order of importance.

To create a custom ranking rule, give an attribute followed by a colon (:) and either asc for ascending order or desc for descending order.

• To apply an ascending sort (results sorted by increasing value): attribute_name:asc
• To apply a descending sort (results sorted by decreasing value): attribute_name:desc

To learn more about ranking rules, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/ranking-rules' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc",
    "rank:desc"
  ]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the ranking rules of an index to their default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/ranking-rules'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

The values associated with attributes in the searchableAttributes list are searched for matching query words. The order of the list also determines the attribute ranking order.

By default, the searchableAttributes array is equal to all fields in your dataset. This behavior is represented by the value ["*"].

To learn more about searchable attributes, refer to our dedicated guide.

Get the searchable attributes of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/searchable-attributes'

[
  "title",
  "overview",
  "genres",
  "release_date.year"
]

Update the searchable attributes of an index.

[<String>, <String>, …]

An array of strings. Each string should be an attribute that exists in the selected index. The array should be given in order of importance: from the most important attribute to the least important attribute.

If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: "searchableAttributes": ["release_date.year"].

To learn more about searchable attributes, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "title",
    "overview",
    "genres"
  ]'

In this example, a document with a match in title will be more relevant than another document with a match in overview.

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the searchable attributes of the index to the default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/searchable-attributes'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Configure the maximum duration of a search query. Meilisearch will interrupt any search taking longer than the cutoff value.

By default, Meilisearch interrupts searches after 1500 milliseconds.

Get an index's search cutoff value.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'

null

Update an index's search cutoff value.

150

A single integer indicating the cutoff value in milliseconds.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms' \
  -H 'Content-Type: application/json' \
  --data-binary '150'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-03-21T06:33:41.000000Z"
}

Use this taskUid to get more details on the status of the task.

Reset an index's search cutoff value to its default value, null. This translates to a cutoff of 1500ms.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-03-21T07:05:16.000000Z"
}

Configure strings as custom separator tokens indicating where a word ends and begins.

Tokens in the separatorTokens list are added on top of Meilisearch's default list of separators. To remove separators from the default list, use the nonSeparatorTokens setting.

Get an index's list of custom separator tokens.

curl \
  -X GET 'http://localhost:7700/indexes/articles/settings/separator-tokens'

[]

Update an index's list of custom separator tokens.

["|", "…"]

An array of strings, with each string indicating a word separator.

curl \
  -X PUT 'http://localhost:7700/indexes/articles/settings/separator-tokens' \
  -H 'Content-Type: application/json'  \
  --data-binary '["|", "…"]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

Use this taskUid to get more details on the status of the task.

Reset an index's list of custom separator tokens to its default value, [].

curl \
  -X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

Use this taskUid to get more details on the status of the task.

Remove tokens from Meilisearch's default list of word separators.

Get an index's list of non-separator tokens.

curl \
  -X GET 'http://localhost:7700/indexes/articles/settings/non-separator-tokens'

[]

Update an index's list of non-separator tokens.

["@", "#"]

An array of strings, with each string indicating a token present in list of word separators.

curl \
  -X PUT 'http://localhost:7700/indexes/articles/settings/non-separator-tokens' \
  -H 'Content-Type: application/json'  \
  --data-binary '["@", "#"]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

Use this taskUid to get more details on the status of the task.

Reset an index's list of non-separator tokens to its default value, [].

curl \
  -X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

Use this taskUid to get more details on the status of the task.

Attributes that can be used when sorting search results using the sort search parameter.

To learn more about sortable attributes, refer to our dedicated guide.

Get the sortable attributes of an index.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/sortable-attributes'

[
  "price",
  "author.surname"
]

Update an index's sortable attributes list.

You can read more about sorting at query time on our dedicated guide.

[<String>, <String>, …]

An array of strings. Each string should be an attribute that exists in the selected index.

If an attribute contains an object, you can use dot notation to set one or more of its keys as a value for this setting: "sortableAttributes": ["author.surname"].

To learn more about sortable attributes, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings/sortable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "price",
    "author"
  ]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset an index's sortable attributes list back to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/sortable-attributes'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Words added to the stopWords list are ignored in future search queries.

Get the stop words list of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/stop-words'

[
  "of",
  "the",
  "to"
]

Update the list of stop words of an index.

[<String>, <String>, …]

An array of strings. Each string should be a single word.

If a list of stop words already exists, it will be overwritten (replaced).

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "the",
    "of",
    "to"
  ]'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the list of stop words of an index to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/stop-words'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

The synonyms object contains words and their respective synonyms. A synonym in Meilisearch is considered equal to its associated word for the purposes of calculating search results.

To learn more about synonyms, refer to our dedicated guide.

Get the list of synonyms of an index.

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/synonyms'

{
  "wolverine": [
    "xmen",
    "logan"
  ],
  "logan": [
    "wolverine",
    "xmen"
  ],
  "wow": [
    "world of warcraft"
  ]
}

Update the list of synonyms of an index. Synonyms are normalized.

{
  <String>: [<String>, <String>, …],
  …
}

An object that contains all synonyms and their associated words. Add the associated words in an array to set a synonym for a word.

To learn more about synonyms, refer to our dedicated guide.

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "wolverine": [
      "xmen",
      "logan"
    ],
    "logan": [
      "wolverine",
      "xmen"
    ],
    "wow": ["world of warcraft"]
  }'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Reset the list of synonyms of an index to its default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/synonyms'

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

You can use this taskUid to get more details on the status of the task.

Typo tolerance helps users find relevant results even when their search queries contain spelling mistakes or typos. This setting allows you to configure the minimum word size for typos and disable typo tolerance for specific words or attributes.

To learn more about typo tolerance, refer to our dedicated guide.

Get the typo tolerance settings of an index.

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/typo-tolerance'

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

Partially update the typo tolerance settings for an index.

{
  "enabled": <Boolean>,
  "minWordSizeForTypos": {
    "oneTypo": <Integer>,
    "twoTypos": <Integer>
  },
  "disableOnWords": [<String>, <String>, …],
  "disableOnAttributes": [<String>, <String>, …]
}

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/typo-tolerance' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "minWordSizeForTypos": {
      "oneTypo": 4,
      "twoTypos": 10
    },
    "disableOnAttributes": ["title"]
  }'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

You can use the returned taskUid to get more details on the status of the task.

Reset an index's typo tolerance settings to their default value.

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/typo-tolerance'

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

You can use the returned taskUid to get more details on the status of the task.

Embedders translate documents and queries into vector embeddings. You must configure at least one embedder to use AI-powered search.

The embedders object may contain up to 256 embedder objects. Each embedder object must be assigned a unique name:

{
  "default": {
    "source": "huggingFace",
    "model": "BAAI/bge-base-en-v1.5",
    "documentTemplate": "A movie titled '{{doc.title}}' whose description starts with {{doc.overview|truncatewords: 20}}"
  },
  "openai": {
    "source": "openAi",
    "apiKey": "OPENAI_API_KEY",
    "model": "text-embedding-3-small",
    "documentTemplate": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords: 20}}",
  }
}

These embedder objects may contain the following fields:

Get the embedders configured for an index.

curl \
  -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/embedders'

{
  "default": {
    "source":  "openAi",
    "apiKey": "OPENAI_API_KEY",
    "model": "text-embedding-3-small",
    "documentTemplate": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords: 20}}",
    "dimensions": 1536
  }
}

Partially update the embedder settings for an index. When this setting is updated Meilisearch may reindex all documents and regenerate their embeddings.

{
  "default": {
    "source": <String>,
    "url": <String>,
    "apiKey": <String>,
    "model": <String>,
    "documentTemplate": <String>,
    "documentTemplateMaxBytes": <Integer>,
    "dimensions": <Integer>,
    "revision": <String>,
    "distribution": {
      "mean": <Float>,
      "sigma": <Float>
    },
    "request": { … },
    "response": { … },
    "headers": { … },
    "binaryQuantized": <Boolean>
  }
}

Set an embedder to null to remove it from the embedders list.

Use source to configure an embedder's source. The following embedders can auto-generate vectors for documents and queries:

• openAi
• huggingFace
• ollama

Additionally, use rest to auto-generate embeddings with any embedder offering a REST API.

You may also configure a userProvided embedder. In this case, you must manually include vector data in your documents' _vector field. You must also manually generate vectors for search queries.

This field is mandatory.

Meilisearch queries url to generate vector embeddings for queries and documents. url must point to a REST-compatible embedder. You may also use url to work with proxies, such as when targeting openAi from behind a proxy.

This field is mandatory when using rest embedders.

This field is optional when using ollama and openAi embedders.

This field is incompatible with huggingFace and userProvided embedders.

Authentication token Meilisearch should send with each request to the embedder.

This field is mandatory if using a protected rest embedder.

This field is optional for openAI and ollama embedders. If you don't specify apiKey, Meilisearch will attempt to read it from environment variables OPENAI_API_KEY and MEILI_OLLAMA_URL, respectively.

This field is incompatible with huggingFace and userProvided embedders.

The model your embedder uses when generating vectors. These are the officially supported models Meilisearch supports:

• openAi: text-embedding-3-small, text-embedding-3-large, openai-text-embedding-ada-002
• huggingFace: BAAI/bge-base-en-v1.5

Other models, such as HuggingFace's BERT models or those provided by Ollama and REST embedders may also be compatible with Meilisearch.

This field is mandatory for Ollama embedders.

This field is optional for openAi and huggingFace. By default, Meilisearch uses text-embedding-3-small and BAAI/bge-base-en-v1.5 respectively.

This field is incompatible with rest and userProvided embedders.

documentTemplate is a string containing a Liquid template. Meillisearch interpolates the template for each document and sends the resulting text to the embedder. The embedder then generates document vectors based on this text.

You may use the following context values:

• {{doc.FIELD}}: doc stands for the document itself. FIELD must correspond to an attribute present on all documents value will be replaced by the value of that field in the input document
• {{fields}}: a list of all the fields appearing in any document in the index. Each field object in this list has the following properties:
  • name: the field's attribute
  • value: the field's value
  • is_searchable: whether the field is present in the searchable attributes list

If a field does not exist in a document, its value is nil.

For best results, build short templates that only contain highly relevant data. If working with a long field, consider truncating it. If you do not manually set it, documentTemplate will include all searchable and non-null document fields. This may lead to suboptimal performance and relevancy.

This field is optional but strongly encouraged for all embedders.

The maximum size of a rendered document template. Longer texts are truncated to fit the configured limit.

documentTemplateMaxBytes must be an integer. It defaults to 400.

This field is optional for all embedders.

Number of dimensions in the chosen model. If not supplied, Meilisearch tries to infer this value.

In most cases, dimensions should be the exact same value of your chosen model. Setting dimensions to a value lower than the model may lead to performance improvements and is only supported in the following OpenAI models:

• openAi: text-embedding-3-small, text-embedding-3-large

This field is mandatory for userProvided embedders.

This field is optional for openAi, huggingFace, ollama, and rest embedders.

Use this field to use a specific revision of a model.

This field is optional for the huggingFace embedder.

This field is incompatible with all other embedders.

request must be a JSON object with the same structure and data of the request you must send to your rest embedder.

The field containing the input text Meilisearch should send to the embedder must be replaced with "{{text}}":

{
  "source": "rest",
  "request": {
    "prompt": "{{text}}"
    …
  },
  …
}

If sending multiple documents in a single request, replace the input field with ["{{text}}", "{{..}}"]:

{
  "source": "rest",
  "request": {
    "prompt": ["{{text}}", "{{..}}"]
    …
  },
  …
}

This field is mandatory when using the rest embedder.

This field is incompatible with all other embedders.

response must be a JSON object with the same structure and data of the response you expect to receive from your rest embedder.

The field containing the embedding itself must be replaced with "{{embedding}}":

{
  "source": "rest",
  "response": {
    "data": "{{embedding}}"
    …
  },
  …
}

If a single response includes multiple embeddings, the field containing the embedding itself must be an array with two items. One must declare the location and structure of a single embedding, while the second item should be "{{..}}":

{
  "source": "rest",
  "response": {
    "data": [
      {
        "embedding": "{{embedding}}"
      },
      "{{..}}"
    ]
    …
  },
  …
}

This field is mandatory when using the rest embedder.

This field is incompatible with all other embedders.

For mathematical reasons, the _rankingScore of semantic search results tend to be closely grouped around an average value that depends on the embedder and model used. This may result in relevant semantic hits being underrepresented and irrelevant semantic hits being overrepresented compared with keyword search hits.

Use distribution when configuring an embedder to correct the returned _rankingScores of the semantic hits with an affine transformation:

curl \
  -X PATCH 'http://localhost:7700/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "huggingFace",
        "model": "MODEL_NAME",
        "distribution": {
          "mean": 0.7,
          "sigma": 0.3
        }
      }
    }
  }'

Configuring distribution requires a certain amount of trial and error, in which you must perform semantic searches and monitor the results. Based on their rankingScores and relevancy, add the observed mean and sigma values for that index.

distribution is an optional field compatible with all embedder sources. It must be an object with two fields:

• mean: a number between 0 and 1 indicating the semantic score of "somewhat relevant" hits before using the distribution setting
• sigma: a number between 0 and 1 indicating the average absolute difference in _rankingScores between "very relevant" hits and "somewhat relevant" hits, and "somewhat relevant" hits and "irrelevant hits".

Changing distribution does not trigger a reindexing operation.

headers must be a JSON object whose keys represent the name of additional headers to send in requests to embedders, and whose values represent the value of these additional headers.

By default, Meilisearch sends the following headers with all requests to rest embedders:

• Authorization: Bearer EMBEDDER_API_KEY (only if apiKey was provided)
• Content-Type: application/json

If headers includes one of these fields, the explicitly declared values take precedence over the defaults.

This field is optional when using the rest embedder.

This field is incompatible with all other embedders.

When set to true, compresses vectors by representing each dimension with 1-bit values. This reduces the relevancy of semantic search results, but greatly reduces database size.

This option can be useful when working with large Meilisearch projects. Consider activating it if your project contains more than one million documents and uses models with more than 1400 dimensions.

curl \
  -X PATCH 'http://localhost:7700/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "openAi",
        "apiKey": "anOpenAiApiKey",
        "model": "text-embedding-3-small",
        "documentTemplate": "A document titled '{{doc.title}}' whose description starts with {{doc.overview|truncatewords: 20}}"
      }
    }
  }'

{
  "taskUid": 1,
  "indexUid": "kitchenware",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2024-05-11T09:33:12.691402Z"
}

You can use the returned taskUid to get more details on the status of the task.