The /settings route allows you to customize search settings for the given index.
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.
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.
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.
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".
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:
Copy
"dictionary": ["W. E. B.", "W.E.B."],"synonyms": { "W. E. B.": ["W.E.B."], "W.E.B.": ["W. E. B."]}
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"].
If the field does not exist, no error will be thrown.
The distinct attribute is a field whose value will always be unique in the returned documents.
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.
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".
If the field does not exist, no error will be thrown.
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.
Setting maxValuesPerFacet to a high value might negatively impact performance.
The following code sample sets maxValuesPerFacet to 2, sorts the genres facet by descending count, and all other facets in ascending alphanumeric order:
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").
Attributes in the filterableAttributes list can be used as filters or facets.
Updating filterable attributes will re-index all documents in the index, which can take some time. To reduce RAM consumption, first update your index settings and then add documents.
features allows you to decide which filter features are allowed for the specified attributes. It accepts the following fields:
facetSearch: Whether facet search should be enabled for the specified attributes. Boolean, defaults to false
filter: A list outlining the filter types for the specified attributes. Must be an object and accepts the following fields:
equality: Enables =, !=, IN, EXISTS, IS NULL, IS EMPTY, NOT, AND, and OR. Boolean, defaults to true
comparison: Enables >, >=, <, <=, TO, EXISTS, IS NULL, IS EMPTY, NOT, AND, and OR. Boolean, defaults to false
Calculating comparison filters is a resource-intensive operation. Disabling them may lead to better search and indexing performance. equality filters use fewer resources and have limited impact on performance.
Use the simple string syntax to match reserved attributes. Reserved Meilisearch fields are always prefixed with an underscore (_), such as _geo and _vector.If set as a filterable attribute, reserved attributes ignore the features field and automatically activate all search features. Reserved fields will not be matched by wildcard attributePatterns such as _*.
An array of strings containing the attributes that can be used as filters at query time. All filter types are enabled for the specified attributes when using the array of strings format.You may also use an array of objects:
If the specified field does not exist, Meilisearch will silently ignore it.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"] or "attributePatterns": ["release_date.year"].
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 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.
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.
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.
The maximum number of search results Meilisearch can return
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.
The maximum number of search results Meilisearch can return
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.
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
Processing filterable attributes for facet search is a resource-intensive operation. This feature is enabled by default, but disabling it may speed up indexing.facetSearch accepts a single Boolean value. If set to false, it disables facet search for the whole index. Meilisearch returns an error if you try to access the /facet-search endpoint when facet search is disabled.
Prefix search is the process through which Meilisearch matches documents that begin with a specific query term, instead of only exact matches. This is a resource-intensive operation that happens during indexing by default.Use prefixSearch to change how prefix search works. It accepts one of the following strings:
"indexingTime": calculate prefix search during indexing. This is the default behavior
"disabled": do not calculate prefix search. May speed up indexing, but will severely impact search result relevancy
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
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.
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 ["*"].
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.
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.
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"].
If the field does not exist, no error will be thrown.
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.
Attributes that can be used when sorting search results using the sort search parameter.
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.
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"].
If the field does not exist, no error will be thrown.
Words added to the stopWords list are ignored in future search queries.
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.
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 open-source project on GitHub 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.
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.
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.
The embedders object may contain up to 256 embedder objects. Each embedder object must be assigned a unique name:
Copy
{ "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 %} {% if field.is_searchable and not field.value == nil %}{{ field.name }}: {{ field.value }} {% endif %} {% endfor %}
Template defining the data Meilisearch sends to the embedder
documentTemplateMaxBytes
Integer
400
Maximum allowed size of rendered document template
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 response Meilisearch expects from the remote embedder
binaryQuantized
Boolean
Empty
Once set to true, irreversibly converts all vector dimensions to 1-bit values
indexingEmbedder
Object
Empty
Configures embedder to vectorize documents during indexing
Partially update the embedder settings for an index. When this setting is updated Meilisearch may reindex all documents and regenerate their embeddings.
Set an embedder to null to remove it from the embedders list.
source
Use source to configure an embedder’s source. The source corresponds to a service that generates embeddings from your documents.Meilisearch supports the following sources:
openAi
huggingFace
ollama
rest
userProvided
compositeexperimental
rest is a generic source compatible with any embeddings provider offering a REST API.Use userProvided when you want to generate embeddings manually. In this case, you must include vector data in your documents’ _vectors field. You must also generate vectors for search queries.This field is mandatory.
Composite embedders experimental
Choose composite to use one embedder during indexing time, and another embedder at search time. Must be used together with indexingEmbedder and searchEmbedder.
This is an experimental feature. Use the experimental features endpoint to activate it:
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. ollama URLs must end with either /api/embed or /api/embeddings.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 when using openAI, Meilisearch attempts to read it from the OPENAI_API_KEY environment variable.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:
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 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 incompatible with userProvided embedders.This field is optional but strongly encouraged for all other embedders.
documentTemplateMaxBytes
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 incompatible with userProvided embedders.This field is optional for all other 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:
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}}":
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}}":
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 "{{..}}":
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 _rankingScores of the semantic hits with an affine transformation:
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
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.
binaryQuantized
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.
Activating binaryQuantized is irreversible. Once enabled, Meilisearch converts all vectors and discards all vector data that does fit within 1-bit. The only way to recover the vectors’ original values is to re-vectorize the whole index in a new embedder.
pooling
Configure how Meilisearch should merge individual tokens into a single embedding.pooling must be one of the following strings:
"useModel": Meilisearch will fetch the pooling method from the model configuration. Default value for new embedders
"forceMean": always use mean pooling. Default value for embedders created in Meilisearch <=v1.13
"forceCls": always use CLS pooling
If in doubt, use "useModel". "forceMean" and "forceCls" are compatibility options that might be necessary for certain embedders and models.pooling is optional for embedders with the huggingFace source.pooling is invalid for all other embedder sources.
indexingEmbedder and searchEmbedderexperimental
When using a composite embedder, configure separate embedders Meilisearch should use when vectorizing documents and search queries.indexingEmbedder often benefits from the higher bandwidth and speed of remote providers so it can vectorize large batches of documents quickly. searchEmbedder may often benefits from the lower latency of processing queries locally.Both fields must be an object and accept the same fields as a regular embedder, with the following exceptions:
indexingEmbedder and searchEmbedder must use the same model for generating embeddings
indexingEmbedder and searchEmbedder must have identical dimensions and pooling methods
source is mandatory for both indexingEmbedder and searchEmbedder
Neither sub-embedder can set source to composite or userProvided
Neither binaryQuantized and distribution are valid sub-embedder fields and must always be declared in the main embedder
documentTemplate and documentTemplateMaxBytes are invalid fields for searchEmbedder
documentTemplate and documentTemplateMaxBytes are mandatory for indexingEmbedder, if applicable to its source
indexingEmbedder and searchEmbedder are mandatory when using the composite source.indexingEmbedder and searchEmbedder are incompatible with all other embedder sources.
The chat settings allow you to configure how your index integrates with Meilisearch’s conversational search feature. This enables the chat completions endpoint to search your index and generate responses based on your documents.
