Index settings

This page describes the index-level settings available in Meilisearch and how to customize them.

Variable	Description	Default value
displayedAttributes	Fields displayed in the returned documents	All attributes found in the documents
distinctAttribute	Search returns documents with distinct (different) values of the given field	null
filterableAttributes	List of attributes that can be used for filtering	null
rankingRules	List of ranking rules sorted by order of importance	A list of ordered built-in ranking rules
searchableAttributes	Fields in which to search for matching query words sorted by order of importance	All attributes found in the documents
sortableAttributes	[Strings]	Attributes to use when sorting search results
stopWords	List of words ignored by Meilisearch when present in search queries	[]
synonyms	List of associated words treated similarly	{}
typoTolerance	Object containing typo tolerance settings	Enabled. One typo allowed for words of 5+ characters; two for words of 9+ characters.

Displayed attributes

The fields whose attributes are added to the displayed-attributes list are contained in each matching document.

Documents returned upon search contain only displayed fields.

displayedAttributes=[<String>, <String>, ...]

• [<String>, <String>, ...] (Array of strings, defaults to all attributes found in the documents)

  An array of strings that contains attributes of an index to display.

Learn more about displayed attributes

Example

By adding the following settings, documents returned upon search will contain the fields title, overview, genres and release_date.

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

client.index('movies').updateSettings({
  displayedAttributes: [
    'title',
    'overview',
    'genres',
    'release_date',
  ]
})

client.index('movies').update_settings({
  'displayedAttributes': [
    'title',
    'overview',
    'genres',
    'release_date'
  ]
})

$client->index('movies')->updateSettings([
  'displayedAttributes' => [
    'title',
    'overview',
    'genres',
    'release_date'
  ]
]);

Settings settings = new Settings();
settings.setDisplayedAttributes(new String[]
{
  "title",
  "overview",
  "genres",
  "release_date"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_settings({
  displayed_attributes: [
    'title',
    'overview',
    'genres',
    'release_date'
  ]
})

settings := meilisearch.Settings{
  DisplayedAttributes: []string{
    "title",
    "overview",
    "genres",
    "release_date",
  },
}
client.Index("movies").UpdateSettings(&settings)

let settings = Settings::new()
  .with_displayed_attributes([
    "title",
    "overview",
    "genres",
    "release_date"
  ]);

let task: Task = client.index("movies").set_settings(&settings).await.unwrap();

let settings = Setting(
  displayedAttributes: [
    "title",
    "overview",
    "genres",
    "release_date"
])
client.index("movies").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateSettings(IndexSettings(
    displayedAttributes: ['title', 'overview', 'genres', 'release_date']));

Distinct attribute

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

distinctAttribute=<String>

• <String> (String, defaults to null)

  The field name.

Learn more about the distinct attribute

Example

Suppose you have an e-commerce dataset. For an index that contains information about jackets, you may have several identical items in different variations (color or size).

As shown below, you have 2 documents that contain information about the same jacket. One of the jackets is brown and the other one is black.

[
  {
    "id": 1,
    "description": "Leather jacket",
    "brand": "Lee jeans",
    "color": "brown",
    "product_id": "123456"
  },
  {
    "id": 2,
    "description": "Leather jacket",
    "brand": "Lee jeans",
    "color": "black",
    "product_id": "123456"
  }
]

You may want to ignore the different colors of an item. To do so, you can set product_id as a distinctAttribute.

curl \
  -X POST 'http://localhost:7700/indexes/jackets/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
      "distinctAttribute": "product_id"
  }

client.index('jackets').updateSettings({
  distinctAttribute: 'product_id'
})

client.index('jackets').update_settings({
  'distinctAttribute': 'product_id'
})

$client->index('jackets')->updateSettings([
  'distinctAttribute' => 'product_id'
]);

Settings settings = new Settings();
settings.setDistinctAttribute("product_id");
client.index("jackets").updateSettings(settings);

client.index('jackets').update_distinct_attribute('product_id')

distinctAttribute := "product_id"
settings := meilisearch.Settings{
  DistinctAttribute: &distinctAttribute,
}
client.Index("jackets").UpdateSettings(&settings)

let settings = Settings::new()
  .with_distinct_attribute("product_id");

let task: Task = client.index("jackets").set_settings(&settings).await.unwrap();

let settings = Setting(
  distinctAttribute: "product_id"
)
client.index("jackets").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client
    .index('jackets')
    .updateSettings(IndexSettings(distinctAttribute: 'product_id'));

With the settings in the example above, only one of the two documents will be returned if you search Lee leather jacket.

Filterable attributes

List of attributes that can be used for filtering and faceted search.

By default, filterableAttributes is an empty array. It expects an array of attributes whose corresponding values are either numbers or strings. null fields or fields that contain empty arrays are silently ignored, but an error will be thrown if the field's value is an object.

TIP

Configuring filterableAttributes is necessary in order to use the filter search parameter.

Learn more about filtering and faceted search in our dedicated guide.

Example

To be able to filter search results on director and genres in a movie database, you must first add these attributes to the filterableAttributes list:

curl \
  -X POST 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
      "filterableAttributes": [
          "director",
          "genres"
      ]
  }'

client.index('movies')
  .updateFilterableAttributes([
    'director',
    'genres'
  ])

client.index('movies').update_filterable_attributes([
    'director',
    'genres',
])

$client->index('movies')->updateFilterableAttributes(['director', 'genres']);

client.index("movies").updateFilterableAttributesSettings(new String[]
{
  "director",
  "genres"
});

client.index('movies').update_filterable_attributes([
  'director',
  'genres'
])

resp, err := client.Index("movies").UpdateFilterableAttributes(&[]string{
  "director",
  "genres",
})

let task: Task = client.index("movies").set_filterable_attributes(["director", "genres"]).await.unwrap();

client.index("movies").updateFilterableAttributes(["genre", "director"]) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateFilterableAttributes([
  'director',
  'genres',
]);

Ranking rules

Built-in ranking rules that ensure relevancy in search results. Ranking rules are applied in a default order which can be changed in the settings. You can add or remove rules and change their order of importance.

rankingRules=[<String>, <String>, ...]

• [<String>, <String>, ...] (Array of strings, see default value below)

  An array of strings that contains the ranking rules sorted by order of importance (arranged from the most important rule to the least important rule).

Default value (the ranking rules in the default order):

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

Read this guide to know more about what each ranking rules does

Custom ranking rule

You can add a custom ranking rule anywhere in the list of ranking rules. A custom ranking rule is composed of an attribute and an ascending or descending order. The attribute must have a numeric value in the documents.

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.

We recommend that all your documents contain any attribute used in a custom ranking rule. For example, if you set the custom ranking rule desc(year), make sure that all your documents contain the attribute year.

Example

To add your ranking rules to the settings, send:

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

client.index('movies').updateSettings({
  rankingRules: [
      'words',
      'typo',
      'proximity',
      'attribute',
      'sort',
      'exactness',
      'release_date:asc',
      'rank:desc'
  ]
})

client.index('movies').update_settings({
  'rankingRules': [
      'words',
      'typo',
      'proximity',
      'attribute',
      'sort',
      'exactness',
      'release_date:asc',
      'rank:desc'
  ]
})

$client->index('movies')->updateSettings([
  'rankingRules' => [
    'words',
    'typo',
    'proximity',
    'attribute',
    'sort',
    'exactness',
    'release_date:asc',
    'rank:desc'
  ]
]);

Settings settings = new Settings();
settings.setRankingRules(new String[]
{
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  "release_date:asc",
  "rank_desc"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_settings({
  ranking_rules: [
    'words',
    'typo',
    'proximity',
    'attribute',
    'sort',
    'exactness',
    'release_date:asc',
    'rank:desc'
  ]
})

settings := meilisearch.Settings{
  RankingRules: []string{
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc",
    "rank:desc",
  },
}
client.Index("movies").UpdateSettings(&settings)

let settings = Settings::new()
  .with_ranking_rules([
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc",
    "rank:desc",
  ]);

let task = client.index("movies").set_settings(&settings).await.unwrap();

let settings = Setting(
  rankingRules: [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc",
    "rank:desc"
])
client.index("movies").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateSettings(IndexSettings(rankingRules: [
      'words',
      'typo',
      'proximity',
      'attribute',
      'sort',
      'exactness',
      'release_date:asc',
      'rank:desc'
    ]));

With the settings in the example above, documents will be sorted by decreasing number of matched query terms first. If too many documents have the same number of query terms, the typo rule will be applied. This operation will be repeated with the next rule until the requested number of documents has been reached (default: 20).

Searchable attributes

The content of the fields whose attributes are added to the searchable-attributes list are searched for matching query words.

searchableAttributes=[<String>, <String>, ...]

• [<String>, <String>, ...] (Array of strings, defaults to all attributes found in the documents)

  An array of strings that contains searchable attributes ordered by importance (arranged from the most important attribute to the least important attribute).

Learn more about searchable attributes

Example

By adding the following settings, the fields title, overview and genres will be searched.

curl \
  -X POST 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
      "searchableAttributes": [
          "title",
          "overview",
          "genres"
      ]
  }'

client.index('movies').updateSettings({
  searchableAttributes: [
    'title',
    'overview',
    'genres'
  ]
})

client.index('movies').update_settings({
  'searchableAttributes': [
    'title',
    'overview',
    'genres'
  ]
})

$client->index('movies')->updateSettings([
  'searchableAttributes' => [
    'title',
    'overview',
    'genres'
  ],
]);

Settings settings = new Settings();
settings.setSearchableAttributes(new String[]
{
  "title",
  "overview",
  "genres"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_settings({
  searchable_attributes: [
    'title',
    'overview',
    'genres'
  ]
})

settings := meilisearch.Settings{
  SearchableAttributes: []string{
    "title",
    "overview",
    "genres",
  },
}
client.Index("movies").UpdateSettings(&settings)

let settings = Settings::new()
  .with_searchable_attributes([
    "title",
    "overview",
    "genres"
  ]);

let task: Task = client.index("movies").set_settings(&settings).await.unwrap();

let settings = Setting(
  searchableAttributes: [
    "title",
    "overview",
    "genres"
])
client.index("movies").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('movies').updateSettings(
    IndexSettings(searchableAttributes: ['title', 'overview', 'genres']));

Sortable attributes

List of attributes that can be used for sorting.

By default, sortableAttributes is an empty array. It expects an array of attributes whose corresponding values are either numbers or strings. null fields or fields that contain empty arrays are silently ignored, but an error will be thrown if the field's value is an object.

TIP

Configuring sortableAttributes is necessary in order to use the sort search parameter.

Learn more about sorting in our dedicated guide.

Example

To be able to sort search results according to the attributes price and author in a webshop, you must first add them to the sortableAttributes list:

curl \
  -X POST 'http://localhost:7700/indexes/books/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "sortableAttributes": [
      "price",
      "author"
    ]
  }'

client.index('books').updateSettings({
  sortableAttributes: [
    'author',
    'price'
  ]
})

client.index('books').update_settings({
  'sortableAttributes': [
    'price',
    'author'
  ]
})

$client->index('books')->updateSettings([
  'sortableAttributes' => [
    'price',
    'author'
  ]
]);

Settings settings = new Settings();
settings.setSortableAttributes(new String[]
{
  "price",
  "author",
});
client.index("books").updateSettings(settings);

client.index('books').update_settings({
  sortable_attributes: [
    'price',
    'author'
  ]
})

settings := meilisearch.Settings{
  SortableAttributes: []string{
    "price",
    "author",
  },
}
client.Index("books").UpdateSettings(&settings)

var newSettings = new Settings
{
    SortableAttributes = new string[] { "price", "author" },
};
await client.Index("meteorites").UpdateSettingsAsync(newSettings);

let settings = Settings::new()
  .with_sortable_attributes([
    "author",
    "price"
  ]);

let task: Task = client.index("books").set_settings(&settings).await.unwrap();

let settings = Setting(
  sortableAttributes: [
    "author",
    "price"
])
client.index("books").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client
    .index('books')
    .updateSettings(IndexSettings(sortableAttributes: ['author', 'price']));

Stop words

A set of words defined for an index. Because some words neither add semantic value nor context, you may want to ignore them from your search. Stop words are ignored during search.

stopWords=[<String>, <String>, ...]

• [<String>, <String>, ...] (Array of strings, defaults to [])

  An array of strings that contains the stop words.

Learn more about stop words

Example

To add the, a and an to the stop words list, send:

curl \
  -X POST 'http://localhost:7700/indexes/movies/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
      "stopWords": [
          "the",
          "a",
          "an"
      ]
  }'

client.index('movies').updateSettings({
  stopWords: [
    'the',
    'a',
    'an'
  ]
})

client.index('movies').update_settings({
  'stopWords': [
      'the',
      'a',
      'an'
  ],
})

$client->index('movies')->updateSettings([
  'stopWords' => [
    'the',
    'a',
    'an'
  ],
]);

Settings settings = new Settings();
settings.setStopWords(new String[]
{
  "the",
  "a",
  "an"
});
client.index("movies").updateSettings(settings);

client.index('movies').update_settings({
  stop_words: [
    'the',
    'a',
    'an'
  ]
})

settings := meilisearch.Settings{
  StopWords: []string{
    "the",
    "a",
    "an",
  },
}
client.Index("movies").UpdateSettings(&settings)

let settings = Settings::new()
  .with_stop_words([
    "the",
    "a",
    "an"
  ]);

let task = client.index("movies").set_settings(&settings).await.unwrap();

let settings = Setting(
  stopWords: [
    "the",
    "a",
    "an"
])
client.index("movies").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client
    .index('movies')
    .updateSettings(IndexSettings(stopWords: ['the', 'a', 'an']));

With the settings in the example above, the, a and an are now ignored by the sorting algorithm if they are present in search queries.

Suppose you would like to search the mask in a movie database. Since the is ignored during search, Meilisearch will look for every movie containing mask and not the millions ones containing the. the is a less relevant term than mask and also a very frequent word in English. By adding the to the stop words list, Meilisearch will ignore this word, and thus be faster to answer without losing in relevancy.

Synonyms

A set of words defined for an index. Synonyms are different words that have the same meaning, and thus are treated similarly. If either of the associated words is searched, the same results will be displayed.

synonyms=<Object>

• <Object> (Object, defaults to {}) : { <String>: [<String>, <String>, ...], ... }

  An object that contains words with a list of their associated synonyms. Synonym strings are normalized.

Learn more about synonyms

Example

Suppose you have an e-commerce dataset. For an index that contains information about tops, you decide to create synonyms for sweater and jumper since these two items are very similar.

curl \
  -X POST 'http://localhost:7700/indexes/tops/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
      "synonyms": {
          "sweater": ["jumper"],
          "jumper": ["sweater"]
      }
  }'

client.index('tops').updateSettings({
  synonyms: {
    sweater: ['jumper'],
    jumper: ['sweater']
})

client.index('tops').update_settings({
  'synonyms': {
    sweater: ['jumper'],
    jumper: ['sweater']
  },
})

$client->index('tops')->updateSettings([
  'synonyms' => [
    'sweater' => ['jumper'],
    'jumper' => ['sweater']
  ]
]);

Settings settings = new Settings();
HashMap<String, String[]> synonyms = new HashMap<String, String[]>();
synonyms.put("sweater", new String[] {"jumper"});
synonyms.put("jumper", new String[] {"sweater"});
settings.setSynonyms(synonyms);
client.index("tops").updateSettings(settings);

client.index('tops').update_settings({
  synonyms: {
    sweater: ['jumper'],
    jumper: ['sweater']
  }
})

settings := meilisearch.Settings{
  Synonyms: map[string][]string{
    "sweater": []string{"jumper"},
    "jumper":     []string{"sweater"},
  },
}
client.Index("tops").UpdateSettings(&settings)

let mut synonyms = HashMap::new();
synonyms.insert(String::from("sweater"), vec![String::from("jumper")]);
synonyms.insert(String::from("jumper"), vec![String::from("sweater")]);

let settings = Settings::new()
  .with_synonyms(synonyms);

let task = client.index("tops").set_settings(&settings).await.unwrap();

let settings = Setting(
  synonyms: [
    "sweater": ["jumper"],
    "jumper": ["sweater"]
])
client.index("tops").updateSettings(settings) { (result: Result<Task, Swift.Error>) in
    switch result {
    case .success(let task):
        print(task)
    case .failure(let error):
        print(error)
    }
}

await client.index('tops').updateSettings(IndexSettings(synonyms: {
      'sweater': ['jumper'],
      'jumper': ['sweater']
    }));

By doing so, when searching for black sweater, results for black jumper will also be returned.

Typo tolerance

The typo tolerance settings for an index. Typo tolerance helps users find relevant results even when their search queries contain spelling mistakes or typos.

The typoTolerance object allows you to:

• Enable or disable the typo tolerance feature with the enabled field
• Configure the minimum word size for typos to be handled with minWordSizeForTypos
• Disable typos on specific words with disableOnWords
• Disable typos on specific document attributes with disableOnAttributes

Learn more about typo tolerance

Example

Adding the following settings disables typo tolerance for the title attribute and sets the minimum word size for 2 typos to 12 characters.

curl \
    -X POST 'http://localhost:7700/indexes/movies/settings/typo-tolerance' \
    -H 'Content-Type: application/json' \
    --data-binary '{
      "minWordSizeForTypos": {
        "twoTypos": 12
      },
      "disableOnAttributes": [
        "title"
      ]
    }'

client.index('movies').updateTypoTolerance({
  minWordSizeForTypos: {
    twoTypos: 12
  },
  disableOnAttributes: [
    'title'
  ]
})

client.index('movies').update_typo_tolerance({
  'minWordSizeForTypos': {
    'twoTypos': 12
  },
  'disableOnAttributes': [
    'title'
  ]
})

$client->index('movies')->updateTypoTolerance([
  'minWordSizeForTypos' => [
    'twoTypos' => 12
  ],
  'disableOnAttributes' => [
    'title'
  ]
]);

client.index("movies").UpdateTypoTolerance({
  MinWordSizeForTypos: meilisearch.MinWordSizeForTypo{
    TwoTypos: 12,
  },
  DisableOnAttributes: []string{"title"},
})