Indexes

An index is a group of documents with associated settings. It is comparable to a table in SQL or a collection in MongoDB.

An index is defined by a uid and contains the following information:

• One primary key
• Customizable settings
• An arbitrary number of documents

Suppose you manage a database that contains information about movies, similar to IMDb. You would probably want to keep multiple types of documents, such as movies, TV shows, actors, directors, and more. Each of these categories would be represented by an index in Meilisearch.

Using an index's settings, you can customize search behavior for that index. For example, a movies index might contain documents with fields like movie_id, title, genre, overview, and release_date. Using settings, you could make a movie's title have a bigger impact on search results than its overview, or make the movie_id field non-searchable.

One index's settings do not impact other indexes. For example, you could use a different list of synonyms for your movies index than for your costumes index, even if they're on the same server.

If you try to add documents or settings to an index that does not already exist, Meilisearch will automatically create it for you.

You can explicitly create an index using the create index endpoint. Once created, you can add documents using the add documents endpoint.

While implicit index creation is more convenient, requiring only a single API request, explicit index creation is considered safer for production. This is because implicit index creation bundles multiple actions into a single task. If one action completes successfully while the other fails, the problem can be difficult to diagnose.

The uid is the unique identifier of an index. It is set when creating the index and must be an integer or string containing only alphanumeric characters a-z A-Z 0-9, hyphens - and underscores _.

Once defined, the uid cannot be changed, and you cannot create another index with the same uid.

{
  "uid": "movies",
  "createdAt": "2019-11-20T09:40:33.711324Z",
  "updatedAt": "2019-11-20T10:16:42.761858Z"
}

Every index has a primary key: a required attribute that must be present in all documents in the index. Each document must have a unique value associated with this attribute.

The primary key serves to identify each document, such that two documents in an index can never be completely identical. If you add two documents with the same value for the primary key, they will be treated as the same document: one will overwrite the other. If you try adding documents, and even a single one is missing the primary key, none of the documents will be stored.

You can set the primary key for an index or let it be inferred by Meilisearch. Read more about setting the primary key.

Learn more about the primary field

Index settings can be thought of as a JSON object containing many different options for customizing search behavior.

You can customize the following index settings:

• Displayed and searchable attributes
• Distinct attribute
• Faceting
• Filterable attributes
• Pagination
• Ranking rules
• Sortable attributes
• Stop words
• Synonyms
• Typo tolerance

To change index settings, use the update settings endpoint or any of the child routes.

By default, every document field is searchable and displayed in response to search queries. However, you can choose to set some fields as non-searchable, non-displayed, or both.

You can update these field attributes using the update settings endpoint, or the respective endpoints for displayed attributes and searchable attributes.

Learn more about displayed and searchable attributes.

If your dataset contains multiple similar documents, you may want to return only one on search. Suppose you have numerous black jackets in different sizes in your costumes index. Setting costume_name as the distinct attribute will mean Meilisearch will not return more than one black jacket with the same costume_name.

Designate the distinct attribute using the update settings endpoint or the update distinct attribute endpoint. You can only set one field as the distinct attribute per index.

Learn more about distinct attributes.

Facets are a specific use-case of filters in Meilisearch: whether something is a facet or filter depends on your UI and UX design. Like filters, you need to add your facets to filterableAttributes, then make a search query using the filter search parameter.

By default, Meilisearch returns 100 facet values for each faceted field. You can change this using the update settings endpoint or the update faceting settings endpoint.

Learn more about faceting.

Filtering allows you to refine your search based on different categories. For example, you could search for all movies of a certain genre: Science Fiction, with a rating above 8.

Before filtering on any document attribute, you must add it to filterableAttributes using the update settings endpoint or the update filterable attributes endpoint. Then, make a search query using the filter search parameter.

Learn more about filtering.

To protect your database from malicious scraping, Meilisearch only returns up to 1000 results for a search query. You can change this limit using the update settings endpoint or the update pagination settings endpoint.

Learn more about pagination.

Meilisearch uses ranking rules to sort matching documents so that the most relevant documents appear at the top. All indexes are created with the same built-in ranking rules executed in default order. The order of these rules matters: the first rule has the most impact, and the last rule has the least.

You can alter this order or define custom ranking rules to return certain results first. This can be done using the update settings endpoint or the update ranking rules endpoint.

Learn more about ranking rules.

By default, Meilisearch orders results according to their relevancy. You can alter this sorting behavior to show certain results first.

Add the attributes you'd like to sort by to sortableAttributes using the update settings endpoint or the update sortable attributes endpoint. You can then use the sort search parameter to sort your results in ascending or descending order.

Learn more about sorting.

Your dataset may contain words you want to ignore during search because, for example, they don't add semantic value or occur too frequently (for instance, the or of in English). You can add these words to the stop words list and Meilisearch will ignore them during search.

Change your index's stop words list using the update settings endpoint or the update stop words endpoint. In addition to improving relevancy, designating common words as stop words greatly improves performance.

Learn more about stop words.

Your dataset may contain words with similar meanings. For these, you can define a list of synonyms: words that will be treated as the same or similar for search purposes. Words set as synonyms won't always return the same results due to factors like typos and splitting the query.

Since synonyms are defined for a given index, they won't apply to any other index on the same Meilisearch instance. You can create your list of synonyms using the update settings endpoint or the update synonyms endpoint.

Learn more about synonyms.

Typo tolerance is a built-in feature that helps you find relevant results even when your search queries contain spelling mistakes or typos, for example, typing chickne instead of chicken. This setting allows you to do the following for your index:

• Enable or disable typo tolerance
• Configure the minimum word size for typos
• Disable typos on specific words
• Disable typos on specific document attributes

You can update the typo tolerance settings using the update settings endpoint or the update typo tolerance endpoint.

Learn more about typo tolerance.

Suppose you have an index in production, movies, where your users are currently making search requests. You want to deploy a new version of movies with different settings, but updating it normally could cause downtime for your users. This problem can be solved using index swapping.

To use index swapping, you would create a second index, movies_new, containing all the changes you want to make to movies.

This means that the documents, settings, and task history of movies will be swapped with the documents, settings, and task history of movies_new without any downtime for the search clients. The task history of enqueued tasks is not modified.

Once swapped, your users will still be making search requests to the movies index but it will contain the data of movies_new. You can delete movies_new after the swap or keep it in case something goes wrong and you want to swap back.

Swapping indexes is an atomic transaction: either all indexes are successfully swapped, or none are.

For more information, see the swap indexes endpoint.