Settings

    The /settings route allows you to customize search settings for the given index. You can either modify all of an index's settings at once using the update settings endpoint, or modify each one individually using the child routes.

    For a conceptual overview of index settings, refer to our indexes guide.

    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"
    }
    

    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"
    }
    

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

    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
        }
      }'
    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.

    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.

    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.