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.
Settings interface
Meilisearch Cloud users can manage index settings through the indexes interface and the /settings
route. Users hosting their own Meilisearch instance can only manage index settings through the /settings
route.
Settings object
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
}
All settings
This route allows you to retrieve, configure, or reset all of an index's settings at once.
Get settings
Get the settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings'
Response: 200 Ok
{
"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 settings
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.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
Name | Type | Default value | Description |
---|---|---|---|
dictionary | Array of strings | Empty | List of strings Meilisearch should parse as a single term |
displayedAttributes | Array of strings | All attributes: ["*"] | Fields displayed in the returned documents |
distinctAttribute | String | null | Search returns documents with distinct (different) values of the given field |
faceting | Object | Default object | Faceting settings |
filterableAttributes | Array of strings | Empty | Attributes to use as filters and facets |
pagination | Object | Default object | Pagination settings |
proximityPrecision | String | "byWord" | Precision level when calculating the proximity ranking rule |
rankingRules | Array of strings | ["words", "typo", "proximity", "attribute", "sort", "exactness"] | List of ranking rules in order of importance |
searchableAttributes | Array of strings | All attributes: ["*"] | Fields in which to search for matching query words sorted by order of importance |
searchCutoffMs | Integer | null , or 1500ms | Maximum duration of a search query |
separatorTokens | Array of strings | Empty | List of characters delimiting where one term begins and ends |
nonSeparatorTokens | Array of strings | Empty | List of characters not delimiting where one term begins and ends |
sortableAttributes | Array of strings | Empty | Attributes to use when sorting search results |
stopWords | Array of strings | Empty | List of words ignored by Meilisearch when present in search queries |
synonyms | Object | Empty | List of associated words treated similarly |
typoTolerance | Object | Default object | Typo tolerance settings |
embedders | Object of objects | Default object | Embedder required for performing meaning-based search queries |
Example
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
}'
WARNING
If Meilisearch encounters an error when updating any of the settings in a request, it immediately stops processing the request and returns an error message. In this case, the database settings remain unchanged. The returned error message will only address the first error encountered.
Response: 202 Accepted
{
"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 settings
Reset all the settings of an index to their default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings'
Response: 202 Accepted
{
"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.
Dictionary
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"
.
TIP
User-defined dictionaries can be used together with synonyms. It can be useful to configure Meilisearch so different spellings of an author's initials return the same results:
"dictionary": ["W. E. B.", "W.E.B."],
"synonyms": {
"W. E. B.": ["W.E.B."],
"W.E.B.": ["W. E. B."]
}
Get dictionary
Get an index's user-defined dictionary.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/dictionary'
Response: 200 OK
[]
Update dictionary
Update an index's user-defined dictionary.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
["J. R. R.", "W. E. B."]
Example
curl \
-X PUT 'http://localhost:7700/indexes/books/settings/dictionary' \
-H 'Content-Type: application/json' \
--data-binary '[
"J. R. R.",
"W. E. B."
]'
Response: 202 Accepted
{
"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 dictionary
Reset an index's dictionary to its default value, []
.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/dictionary'
Response: 202 Accepted
{
"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.
Displayed attributes
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 displayed attributes
Get the displayed attributes of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/displayed-attributes'
Response: 200 Ok
[
"title",
"overview",
"genres",
"release_date.year"
]
Update displayed attributes
Update the displayed attributes of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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"]
.
WARNING
If the field does not exist, no error will be thrown.
Example
curl \
-X PUT 'http://localhost:7700/indexes/movies/settings/displayed-attributes' \
-H 'Content-Type: application/json' \
--data-binary '[
"title",
"overview",
"genres",
"release_date"
]'
Response: 202 Accepted
{
"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 displayed attributes
Reset the displayed attributes of the index to the default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/displayed-attributes'
Response: 202 Accepted
{
"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.
Distinct attribute
The distinct attribute is a field whose value will always be unique in the returned documents.
WARNING
Updating distinct attributes will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
To learn more about the distinct attribute, refer to our dedicated guide.
Get distinct attribute
Get the distinct attribute of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/shoes/settings/distinct-attribute'
Response: 200 Ok
"skuid"
Update distinct attribute
Update the distinct attribute field of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
<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"
.
WARNING
If the field does not exist, no error will be thrown.
To learn more about the distinct attribute, refer to our dedicated guide.
Example
curl \
-X PUT 'http://localhost:7700/indexes/shoes/settings/distinct-attribute' \
-H 'Content-Type: application/json' \
--data-binary '"skuid"'
Response: 202 Accepted
{
"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 distinct attribute
Reset the distinct attribute of an index to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/shoes/settings/distinct-attribute'
Response: 202 Accepted
{
"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.
Faceting
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.
Faceting object
Name | Type | Default value | Description |
---|---|---|---|
maxValuesPerFacet | Integer | 100 | Maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order |
sortFacetValuesBy | Object | All facet values are sorted in ascending alphanumeric order ("*": "alpha" ) | Customize facet order to sort by descending value count (count ) or ascending alphanumeric order (alpha ) |
Get faceting settings
Get the faceting settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/faceting'
Response: 200 OK
{
"maxValuesPerFacet": 100,
"sortFacetValuesBy": {
"*": "alpha"
}
}
Update faceting settings
Partially update the faceting settings for an index. Any parameters not provided in the body will be left unchanged.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{
"maxValuesPerFacet": <Integer>,
"sortFacetValuesBy":{
<String>: "count",
<String>: "alpha"
}
}
Name | Type | Default value | Description |
---|---|---|---|
maxValuesPerFacet | Integer | 100 | Maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order |
sortFacetValuesBy | Object | All facet values are sorted in ascending alphanumeric order ("*": "alpha" ) | Customize facet order to sort by descending value count(count ) or ascending alphanumeric order (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.
NOTE
Setting maxValuesPerFacet
to a high value might negatively impact performance.
Example
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"
}
}'
Response: 202 Accepted
{
"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 faceting settings
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"
).
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/faceting'
Response: 200 OK
{
"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.
Filterable attributes
Attributes in the filterableAttributes
list can be used as filters or facets.
WARNING
Updating filterable attributes will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
To learn more about filterable attributes, refer to our dedicated guide.
Get filterable attributes
Get the filterable attributes for an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/filterable-attributes'
Response: 200 Ok
[
"genres",
"director",
"release_date.year"
]
Update filterable attributes
Update an index's filterable attributes list.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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"]
.
WARNING
If the field does not exist, no error will be thrown.
To learn more about filterable attributes, refer to our dedicated guide.
Example
curl \
-X PUT 'http://localhost:7700/indexes/movies/settings/filterable-attributes' \
-H 'Content-Type: application/json' \
--data-binary '[
"genres",
"director"
]'
Response: 202 Accepted
{
"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 filterable attributes
Reset an index's filterable attributes list back to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/filterable-attributes'
Response: 202 Accepted
{
"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.
Localized attributes
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.
`locales` and `localizedAttributes`
locales
and localizedAttributes
have the same goal: explicitly state the language used in a search when Meilisearch's language auto-detection is not working as expected.
If you believe Meilisearch is detecting incorrect languages because of the query text, explicitly set the search language with locales
.
If you believe Meilisearch is detecting incorrect languages because of document, explicitly set the document language at the index level with localizedAttributes
.
For full control over the way Meilisearch detects languages during indexing and at search time, set both locales
and localizedAttributes
.
Localized attributes object
localizedAttributes
must be an array of locale objects. Its default value is []
.
Locale objects must have the following fields:
Name | Type | Default value | Description |
---|---|---|---|
locales | Array of strings | [] | A list of strings indicating one or more ISO-639 locales |
attribute_patterns | Array of strings | [] | A list of strings indicating which fields correspond to the specified locales |
locales
Meilisearch supports the following 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 also assign an empty array to locales
. In this case, Meilisearch will auto-detect the language of the associated attributePatterns
.
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 localized attributes settings
Get the localized attributes settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/localized-attributes'
Response: 200 OK
{
"localizedAttributes": [
{"locales": ["jpn"], "attributePatterns": ["*_ja"]}
]
}
Update localized attribute settings
Update the localized attributes settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{
"localizedAttributes": [
{
"locale": [<String>, …],
"attributePatterns": [<String>, …],
}
]
}
Name | Type | Default value | Description |
---|---|---|---|
localizedAttributes | Array of objects | [] | Explicitly set specific locales for one or more attributes |
Example
Response: 202 Accepted
{
"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 pagination settings
Reset an index's localized attributes to their default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
Response: 202 Accepted
{
"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.
Pagination
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.
Pagination object
Name | Type | Default value | Description |
---|---|---|---|
maxTotalHits | Integer | 1000 | The maximum number of search results Meilisearch can return |
Get pagination settings
Get the pagination settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/pagination'
Response: 200 OK
{
"maxTotalHits": 1000
}
Update pagination settings
Partially update the pagination settings for an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{maxTotalHits: <Integer>}
Name | Type | Default value | Description |
---|---|---|---|
maxTotalHits | Integer | 1000 | The maximum number of search results Meilisearch can return |
WARNING
Setting maxTotalHits
to a value higher than the default will negatively impact search performance. Setting maxTotalHits
to values over 20000
may result in queries taking seconds to complete.
Example
curl \
-X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \
-H 'Content-Type: application/json' \
--data-binary '{
"maxTotalHits": 100
}'
Response: 202 Accepted
{
"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 pagination settings
Reset an index's pagination settings to their default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/pagination'
Response: 202 Accepted
{
"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.
Proximity precision
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 proximity precision settings
Get the proximity precision settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/proximity-precision'
Response: 200 OK
{
"proximityPrecision": "byWord"
}
Update proximity precision settings
Update the pagination settings for an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
"byWord"|"byAttribute"
Example
curl \
-X PUT 'http://localhost:7700/indexes/books/settings/proximity-precision' \
-H 'Content-Type: application/json' \
--data-binary '"byAttribute"'
Response: 202 Accepted
{
"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 proximity precision settings
Reset an index's proximity precision setting to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision'
Response: 202 Accepted
{
"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
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.
Ranking rules array
Name | Description |
---|---|
"words" | Sorts results by decreasing number of matched query terms |
"typo" | Sorts results by increasing number of typos |
"proximity" | Sorts results by increasing distance between matched query terms |
"attribute" | Sorts results based on the attribute ranking order |
"sort" | Sorts results based on parameters decided at query time |
"exactness" | Sorts results based on the similarity of the matched words with the query words |
Default order
[
"words",
"typo",
"proximity",
"attribute",
"sort",
"exactness"
]
Get ranking rules
Get the ranking rules of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/ranking-rules'
Response: 200 Ok
[
"words",
"typo",
"proximity",
"attribute",
"sort",
"exactness",
"release_date:desc"
]
Update ranking rules
Update the ranking rules of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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
WARNING
If some documents do not contain the attribute defined in a custom ranking rule, the application of the ranking rule is undefined and the search results might not be sorted as you expected.
Make sure that any attribute used in a custom ranking rule is present in all of your documents. For example, if you set the custom ranking rule desc(year)
, make sure that all your documents contain the attribute year
.
To learn more about ranking rules, refer to our dedicated guide.
Example
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"
]'
Response: 202 Accepted
{
"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 ranking rules
Reset the ranking rules of an index to their default value.
TIP
Resetting ranking rules is not the same as removing them. To remove a ranking rule, use the update ranking rules endpoint.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/ranking-rules'
Response: 202 Accepted
{
"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.
Searchable attributes
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 ["*"]
.
WARNING
Updating searchable attributes will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
To learn more about searchable attributes, refer to our dedicated guide.
Get searchable attributes
Get the searchable attributes of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/searchable-attributes'
Response: 200 Ok
[
"title",
"overview",
"genres",
"release_date.year"
]
Update searchable attributes
Update the searchable attributes of an index.
WARNING
Due to an implementation bug, manually updating searchableAttributes
will change the displayed order of document fields in the JSON response. This behavior is inconsistent and will be fixed in a future release.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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"]
.
WARNING
If the field does not exist, no error will be thrown.
To learn more about searchable attributes, refer to our dedicated guide.
Example
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
.
Response: 202 Accepted
{
"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 searchable attributes
Reset the searchable attributes of the index to the default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/searchable-attributes'
Response: 202 Accepted
{
"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.
Search cutoff
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 search cutoff
Get an index's search cutoff value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'
Response: 200 Ok
null
Update search cutoff
Update an index's search cutoff value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
150
A single integer indicating the cutoff value in milliseconds.
Example
curl \
-X PUT 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms' \
-H 'Content-Type: application/json' \
--data-binary '150'
Response: 202 Accepted
{
"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 search cutoff
Reset an index's search cutoff value to its default value, null
. This translates to a cutoff of 1500ms.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'
Response: 202 Accepted
{
"taskUid": 1,
"indexUid": "movies",
"status": "enqueued",
"type": "settingsUpdate",
"enqueuedAt": "2023-03-21T07:05:16.000000Z"
}
Separator tokens
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 separator tokens
Get an index's list of custom separator tokens.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/articles/settings/separator-tokens'
Response: 200 Ok
[]
Update separator tokens
Update an index's list of custom separator tokens.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
["|", "…"]
An array of strings, with each string indicating a word separator.
Example
curl \
-X PUT 'http://localhost:7700/indexes/articles/settings/separator-tokens' \
-H 'Content-Type: application/json' \
--data-binary '["|", "…"]'
Response: 202 Accepted
{
"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 separator tokens
Reset an index's list of custom separator tokens to its default value, []
.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'
Response: 202 Accepted
{
"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.
Non-separator tokens
Remove tokens from Meilisearch's default list of word separators.
Get non-separator tokens
Get an index's list of non-separator tokens.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/articles/settings/non-separator-tokens'
Response: 200 Ok
[]
Update non-separator tokens
Update an index's list of non-separator tokens.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
["@", "#"]
An array of strings, with each string indicating a token present in list of word separators.
Example
curl \
-X PUT 'http://localhost:7700/indexes/articles/settings/non-separator-tokens' \
-H 'Content-Type: application/json' \
--data-binary '["@", "#"]'
Response: 202 Accepted
{
"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 non-separator tokens
Reset an index's list of non-separator tokens to its default value, []
.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'
Response: 202 Accepted
{
"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.
Sortable attributes
Attributes that can be used when sorting search results using the sort
search parameter.
WARNING
Updating sortable attributes will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
To learn more about sortable attributes, refer to our dedicated guide.
Get sortable attributes
Get the sortable attributes of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/sortable-attributes'
Response: 200 Ok
[
"price",
"author.surname"
]
Update sortable attributes
Update an index's sortable attributes list.
You can read more about sorting at query time on our dedicated guide.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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"]
.
WARNING
If the field does not exist, no error will be thrown.
To learn more about sortable attributes, refer to our dedicated guide.
Example
curl \
-X PUT 'http://localhost:7700/indexes/books/settings/sortable-attributes' \
-H 'Content-Type: application/json' \
--data-binary '[
"price",
"author"
]'
Response: 202 Accepted
{
"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 sortable attributes
Reset an index's sortable attributes list back to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/sortable-attributes'
Response: 202 Accepted
{
"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.
Stop words
Words added to the stopWords
list are ignored in future search queries.
WARNING
Updating stop words will re-index all documents in the index, which can take some time. We recommend updating your index settings first and then adding documents as this reduces RAM consumption.
TIP
Stop words are strongly related to the language used in your dataset. For example, most datasets containing English documents will have countless occurrences of the
and of
. Italian datasets, instead, will benefit from ignoring words like a
, la
, or il
.
This website maintained by a French developer offers lists of possible stop words in different languages. Note that, depending on your dataset and use case, you will need to tweak these lists for optimal results.
Get stop words
Get the stop words list of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/stop-words'
Response: 200 Ok
[
"of",
"the",
"to"
]
Update stop words
Update the list of stop words of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
[<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).
Example
curl \
-X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \
-H 'Content-Type: application/json' \
--data-binary '[
"the",
"of",
"to"
]'
Response: 202 Accepted
{
"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 stop words
Reset the list of stop words of an index to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/stop-words'
Response: 202 Accepted
{
"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.
Synonyms
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 synonyms
Get the list of synonyms of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/movies/settings/synonyms'
Response: 200 OK
{
"wolverine": [
"xmen",
"logan"
],
"logan": [
"wolverine",
"xmen"
],
"wow": [
"world of warcraft"
]
}
Update synonyms
Update the list of synonyms of an index. Synonyms are normalized.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{
<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.
Example
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"]
}'
Response: 202 Accepted
{
"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 synonyms
Reset the list of synonyms of an index to its default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/movies/settings/synonyms'
Response: 202 Accepted
{
"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
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.
Typo tolerance object
Name | Type | Default Value | Description |
---|---|---|---|
enabled | Boolean | true | Whether typo tolerance is enabled or not |
minWordSizeForTypos.oneTypo | Integer | 5 | The minimum word size for accepting 1 typo; must be between 0 and twoTypos |
minWordSizeForTypos.twoTypos | Integer | 9 | The minimum word size for accepting 2 typos; must be between oneTypo and 255 |
disableOnWords | Array of strings | Empty | An array of words for which the typo tolerance feature is disabled |
disableOnAttributes | Array of strings | Empty | An array of attributes for which the typo tolerance feature is disabled |
Get typo tolerance settings
Get the typo tolerance settings of an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/books/settings/typo-tolerance'
Response: 200 OK
{
"enabled": true,
"minWordSizeForTypos": {
"oneTypo": 5,
"twoTypos": 9
},
"disableOnWords": [],
"disableOnAttributes": []
}
Update typo tolerance settings
Partially update the typo tolerance settings for an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{
"enabled": <Boolean>,
"minWordSizeForTypos": {
"oneTypo": <Integer>,
"twoTypos": <Integer>
},
"disableOnWords": [<String>, <String>, …],
"disableOnAttributes": [<String>, <String>, …]
}
Name | Type | Default Value | Description |
---|---|---|---|
enabled | Boolean | true | Whether typo tolerance is enabled or not |
minWordSizeForTypos.oneTypo | Integer | 5 | The minimum word size for accepting 1 typo; must be between 0 and twoTypos |
minWordSizeForTypos.twoTypos | Integer | 9 | The minimum word size for accepting 2 typos; must be between oneTypo and 255 |
disableOnWords | Array of strings | Empty | An array of words for which the typo tolerance feature is disabled |
disableOnAttributes | Array of strings | Empty | An array of attributes for which the typo tolerance feature is disabled |
Example
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"]
}'
Response: 202 Accepted
{
"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 typo tolerance settings
Reset an index's typo tolerance settings to their default value.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/books/settings/typo-tolerance'
Response: 202 Accepted
{
"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 (experimental)
Embedders translate documents and queries into vector embeddings. You must configure at least one embedder to use AI-powered search.
Embedders object
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:
Name | Type | Default Value | Description |
---|---|---|---|
source | String | Empty | The third-party tool that will generate embeddings from documents. Must be openAi , huggingFace , ollama , rest , or userProvided |
url | String | http://localhost:11434/api/embeddings | The URL Meilisearch contacts when querying the embedder |
apiKey | String | Empty | Authentication token Meilisearch should send with each request to the embedder. If not present, Meilisearch will attempt to read it from environment variables |
model | String | Empty | The model your embedder uses when generating vectors |
documentTemplate | String | {% for field in fields %}{{field.name}}: {{field.value}}\n{% endfor %} | Template defining the data Meilisearch sends the embedder |
dimensions | Integer | Empty | Number of dimensions in the chosen model. If not supplied, Meilisearch tries to infer this value |
revision | String | Empty | Model revision hash |
distribution | Object | Empty | Describes the natural distribution of search results. Must contain two fields, mean and sigma , each containing a numeric value between 0 and 1 |
request | Object | Empty | A JSON value representing the request Meilisearch makes to the remote embedder |
response | Object | Empty | A JSON value representing the request Meilisearch expects from the remote embedder |
Get embedder settings
Get the embedders configured for an index.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/embedders'
Response: 200 OK
{
"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
}
}
Update embedder settings
Partially update the embedder settings for an index. When this setting is updated Meilisearch may reindex all documents and regenerate their embeddings.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Body
{
"default": {
"source": <String>,
"url": <String>,
"apiKey": <String>,
"model": <String>,
"documentTemplate": <String>,
"dimensions": <Integer>,
"revision": <String>,
"distribution": {
"mean": <Float>,
"sigma": <Float>
},
"request": { … },
"response": { … },
"headers": { … }
}
}
Set an embedder to null
to remove it from the embedders list.
source
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.
url
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.
apiKey
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.
model
The model your embedder uses when generating vectors. These are the officially supported models Meilisearch supports:
openAi
:openai-text-embedding-ada-002
,text-embedding-3-small
, andtext-embedding-3-large
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
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 thefield
s appearing in any document in the index. Eachfield
object in this list has two properties:name
andvalue
. If afield
does not exist in a document,value
isnil
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 document fields. This may lead to suboptimal performance and relevancy.
This field is optional but strongly encouraged for all embedders.
dimensions
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.
revision
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
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
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.
distribution
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 _rankingScore
s 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 rankingScore
s 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 between0
and1
indicating the semantic score of "somewhat relevant" hits before using thedistribution
settingsigma
: a number between0
and1
indicating the average absolute difference in_rankingScore
s between "very relevant" hits and "somewhat relevant" hits, and "somewhat relevant" hits and "irrelevant hits".
Changing distribution
does not trigger a reindexing operation.
headers
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 ifapiKey
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.
Example
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}}"
}
}
}'
Response: 202 Accepted
{
"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.
Reset embedder settings
Removes all embedders from your index.
To remove a single embedder, use the update embedder settings endpoint and set the target embedder to null
.
Path parameters
Name | Type | Description |
---|---|---|
index_uid * | String | uid of the requested index |
Example
curl \
-X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/embedders'
Response: 202 Accepted
{
"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.