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/indexes/{index_uid}/settings

    Get the settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PATCH/indexes/{index_uid}/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

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    NameTypeDefault valueDescription
    dictionaryArray of stringsEmptyList of strings Meilisearch should parse as a single term
    displayedAttributesArray of stringsAll attributes: ["*"]Fields displayed in the returned documents
    distinctAttributeStringnullSearch returns documents with distinct (different) values of the given field
    facetingObjectDefault objectFaceting settings
    filterableAttributesArray of stringsEmptyAttributes to use as filters and facets
    paginationObjectDefault objectPagination settings
    proximityPrecisionString"byWord"Precision level when calculating the proximity ranking rule
    rankingRulesArray of strings["words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness"]
    List of ranking rules in order of importance
    searchableAttributesArray of stringsAll attributes: ["*"]Fields in which to search for matching query words sorted by order of importance
    searchCutoffMsIntegernull, or 1500msMaximum duration of a search query
    separatorTokensArray of stringsEmptyList of characters delimiting where one term begins and ends
    nonSeparatorTokensArray of stringsEmptyList of characters not delimiting where one term begins and ends
    sortableAttributesArray of stringsEmptyAttributes to use when sorting search results
    stopWordsArray of stringsEmptyList of words ignored by Meilisearch when present in search queries
    synonymsObjectEmptyList of associated words treated similarly
    typoToleranceObjectDefault objectTypo tolerance settings
    embeddersObject of objectsDefault objectEmbedder 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

    DELETE/indexes/{index_uid}/settings

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/dictionary

    Get an index's user-defined dictionary.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/books/settings/dictionary'
    Response: 200 OK
    []
    

    Update dictionary

    PUT/indexes/{index_uid}/settings/dictionary

    Update an index's user-defined dictionary.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/dictionary

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/displayed-attributes

    Get the displayed attributes of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/displayed-attributes

    Update the displayed attributes of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/displayed-attributes

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/distinct-attribute

    Get the distinct attribute of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/shoes/settings/distinct-attribute'
    Response: 200 Ok
    "skuid"
    

    Update distinct attribute

    PUT/indexes/{index_uid}/settings/distinct-attribute

    Update the distinct attribute field of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/distinct-attribute

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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:

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

    Faceting object

    NameTypeDefault valueDescription
    maxValuesPerFacetInteger100Maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order
    sortFacetValuesByObjectAll 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/indexes/{index_uid}/settings/faceting

    Get the faceting settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PATCH/indexes/{index_uid}/settings/faceting

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    {
      "maxValuesPerFacet": <Integer>,
      "sortFacetValuesBy":{
          <String>: "count",
          <String>: "alpha"
      }
    }
    
    NameTypeDefault valueDescription
    maxValuesPerFacetInteger100Maximum number of facet values returned for each facet. Values are sorted in ascending lexicographical order
    sortFacetValuesByObjectAll 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

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/filterable-attributes

    Get the filterable attributes for an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/filterable-attributes

    Update an index's filterable attributes list.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/filterable-attributes

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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:

    NameTypeDefault valueDescription
    localesArray of strings[]A list of strings indicating one or more ISO-639 locales
    attribute_patternsArray 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/indexes/{index_uid}/settings/localized-attributes

    Get the localized attributes settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/localized-attributes

    Update the localized attributes settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    {
      "localizedAttributes": [
        {
         "locale": [<String>, …],
         "attributePatterns": [<String>, …],
        }
      ]
    }
    
    NameTypeDefault valueDescription
    localizedAttributesArray 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/indexes/{index_uid}/settings/localized-attributes

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    NameTypeDefault valueDescription
    maxTotalHitsInteger1000The maximum number of search results Meilisearch can return

    Get pagination settings

    GET/indexes/{index_uid}/settings/pagination

    Get the pagination settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/books/settings/pagination'
    Response: 200 OK
    {
      "maxTotalHits": 1000
    }
    

    Update pagination settings

    PATCH/indexes/{index_uid}/settings/pagination

    Partially update the pagination settings for an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    {maxTotalHits: <Integer>}
    
    NameTypeDefault valueDescription
    maxTotalHitsInteger1000The 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

    NameTypeDescription
    index_uid *Stringuid 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:

    Get proximity precision settings

    GET/indexes/{index_uid}/settings/proximity-precision

    Get the proximity precision settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/proximity-precision

    Update the pagination settings for an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    NameTypeDescription
    index_uid *Stringuid 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

    NameDescription
    "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/indexes/{index_uid}/settings/ranking-rules

    Get the ranking rules of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/ranking-rules

    Update the ranking rules of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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.

    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

    DELETE/indexes/{index_uid}/settings/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

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/searchable-attributes

    Get the searchable attributes of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/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

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/searchable-attributes

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/search-cutoff-ms

    Get an index's search cutoff value.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

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

    Update search cutoff

    PUT/indexes/{index_uid}/settings/search-cutoff-ms

    Update an index's search cutoff value.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/search-cutoff-ms

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/separator-tokens

    Get an index's list of custom separator tokens.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/articles/settings/separator-tokens'
    Response: 200 Ok
    []
    

    Update separator tokens

    PUT/indexes/{index_uid}/settings/separator-tokens

    Update an index's list of custom separator tokens.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    ["|", "&hellip;"]
    

    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 '["|", "&hellip;"]'
    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

    DELETE/indexes/{index_uid}/settings/separator-tokens

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/non-separator-tokens

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/articles/settings/non-separator-tokens'
    Response: 200 Ok
    []
    

    Update non-separator tokens

    PUT/indexes/{index_uid}/settings/non-separator-tokens

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/non-separator-tokens

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/sortable-attributes

    Get the sortable attributes of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/sortable-attributes

    Update an index's sortable attributes list.

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/sortable-attributes

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/stop-words

    Get the stop words list of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/stop-words

    Update the list of stop words of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/stop-words

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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/indexes/{index_uid}/settings/synonyms

    Get the list of synonyms of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PUT/indexes/{index_uid}/settings/synonyms

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    DELETE/indexes/{index_uid}/settings/synonyms

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    NameTypeDefault ValueDescription
    enabledBooleantrueWhether typo tolerance is enabled or not
    minWordSizeForTypos.oneTypoInteger5The minimum word size for accepting 1 typo; must be between 0 and twoTypos
    minWordSizeForTypos.twoTyposInteger9The minimum word size for accepting 2 typos; must be between oneTypo and 255
    disableOnWordsArray of stringsEmptyAn array of words for which the typo tolerance feature is disabled
    disableOnAttributesArray of stringsEmptyAn array of attributes for which the typo tolerance feature is disabled

    Get typo tolerance settings

    GET/indexes/{index_uid}/settings/typo-tolerance

    Get the typo tolerance settings of an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PATCH/indexes/{index_uid}/settings/typo-tolerance

    Partially update the typo tolerance settings for an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    {
      "enabled": <Boolean>,
      "minWordSizeForTypos": {
        "oneTypo": <Integer>,
        "twoTypos": <Integer>
      },
      "disableOnWords": [<String>, <String>, …],
      "disableOnAttributes": [<String>, <String>, …]
    }
    
    NameTypeDefault ValueDescription
    enabledBooleantrueWhether typo tolerance is enabled or not
    minWordSizeForTypos.oneTypoInteger5The minimum word size for accepting 1 typo; must be between 0 and twoTypos
    minWordSizeForTypos.twoTyposInteger9The minimum word size for accepting 2 typos; must be between oneTypo and 255
    disableOnWordsArray of stringsEmptyAn array of words for which the typo tolerance feature is disabled
    disableOnAttributesArray of stringsEmptyAn 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

    DELETE/indexes/{index_uid}/settings/typo-tolerance

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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:

    NameTypeDefault ValueDescription
    sourceStringEmptyThe third-party tool that will generate embeddings from documents. Must be openAi, huggingFace, ollama, rest, or userProvided
    urlStringhttp://localhost:11434/api/embeddingsThe URL Meilisearch contacts when querying the embedder
    apiKeyStringEmptyAuthentication token Meilisearch should send with each request to the embedder. If not present, Meilisearch will attempt to read it from environment variables
    modelStringEmptyThe model your embedder uses when generating vectors
    documentTemplateString{% for field in fields %}{{field.name}}: {{field.value}}\n{% endfor %}Template defining the data Meilisearch sends the embedder
    dimensionsIntegerEmptyNumber of dimensions in the chosen model. If not supplied, Meilisearch tries to infer this value
    revisionStringEmptyModel revision hash
    distributionObjectEmptyDescribes the natural distribution of search results. Must contain two fields, mean and sigma, each containing a numeric value between 0 and 1
    requestObjectEmptyA JSON value representing the request Meilisearch makes to the remote embedder
    responseObjectEmptyA JSON value representing the request Meilisearch expects from the remote embedder

    Get embedder settings

    GET/indexes/{index_uid}/settings/embedders

    Get the embedders configured for an index.

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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

    PATCH/indexes/{index_uid}/settings/embedders

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

    Path parameters

    NameTypeDescription
    index_uid *Stringuid 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:

    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:

    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:

    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:

    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 _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:

    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:

    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

    DELETE/indexes/{index_uid}/settings/embedders

    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

    NameTypeDescription
    index_uid *Stringuid 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.