How to implement document boosting with a second index

In this guide, we'll walk you through implementing promoted search results with Meilisearch. Our goal is to return search results that prioritize specific documents when certain keywords match a user's query. These boosted documents should be returned at the top of the search results.

How document boosting works

Here's a simplified breakdown of how to implement document boosting using a second index for “pinned documents” and the multi-search feature:

1. Create Indexes: Set up two indexes: one for regular search and one for boosted results. The boosted index will have a special attribute, keywords, to trigger the boosting.
2. Populate the 'games' Index: Populate a games index with your dataset using the provided JSON file. This index will serve as the source for our boosted documents.
3. Configure the 'pinned_games' Index: Configure the pinned_games index to display attributes without revealing keywords. Adjust the searchable and displayed attributes accordingly.
4. Boost Documents: Identify documents you want to boost and assign relevant keywords to them. For instance, you can assign the keywords fps and shooter to the game Counter-Strike.
5. Implement the Multi-Search: Utilize Meilisearch's multi-search feature to perform a search query across both the regular and boosted indexes. This way, boosted documents matching keywords will appear first.
6. Display Results: Present the search results in a user-friendly format, highlighting boosted documents with a visual indicator.

Implementation

Installation

Before diving in, make sure you have Meilisearch up and running. If you haven't installed it yet, follow these steps:

1. Launch a Meilisearch instance, either on Meilisearch Cloud or by running it locally.
2. Ensure you have your favorite language SDK (or framework integration) installed.

Initializing indexes

For our example, we'll work with a dataset of Steam games. You can adapt this process to your own data:

1. Download the steam-games.json and settings.json files for our Steam games dataset
2. Load the dataset in your Meilisearch instance by adding documents from the steam-games.json file.

games index

pinned_games index

This index will contain the promoted documents. The settings of the pinned_games index are the same as the games index, with the following differences:

• the only searchableAttributes is the keywords attribute containing the words that trigger pinning that document.
• the displayedAttributes are all the attributes of the documents, except for keywords (we don't want to show the keywords to end-users)

Updating the promoted documents index

We'll now populate the index with documents from the games index that we want to promote.

As an example, let's say we want to pin the game "Counter-Strike" to the "fps" and "first", "person", "shooter" keywords.

Customizing search results

Now, let’s create a function to return the search results with the pinned documents.

We can use this function to retrieve our search results with promoted documents:

The results object should look like:

You now have a search results object that contains two arrays: the promoted results and the regular ones.

Going further

This tutorial explored one approach for implementing promoted results. An alternative technique would be implementing documents pinning in the frontend; take a look at our React implementation guide. That different approach has the benefit of being compatible with InstantSearch.

Both techniques achieve similar results. Since this guide was first published, promoted documents have landed in the engine itself as search rules, so it is worth checking whether a rule covers your case before building either workaround.

For more things Meilisearch, you can subscribe to our newsletter. You can learn more about our product by checking out the roadmap and participating in our product discussions.

For anything else, join our developers community on Discord.

Cheers!

Frequently asked questions (FAQs)

What is document boosting in Meilisearch?

Document boosting promotes chosen documents to the top of a result set when a query matches keywords you control. Meilisearch ranks results with its own ranking rules, so boosting sits on top of that: you either pin documents natively with search rules, or keep a second index of promoted documents and merge it into the results with multi-search, as this guide does.

Does Meilisearch support promoted results natively?

Yes. Search rules pin selected documents at fixed positions when query, time, or filter conditions match. The feature is experimental and is enabled per project, with three rules included for free. The second-index technique in this guide predates it and is still useful when you want the promotion logic in your own application code.

Why use a second index instead of a filter on the main index?

A second index keeps the keywords that trigger promotion out of your main index, so they never affect normal relevancy and are never returned to users. Querying both indexes in a single multi-search request also keeps it to one round trip.

How many promoted documents does a search return?

As many as match the keywords in the pinned index, up to the limit set on the query. The example function fills the remaining slots from the regular index, so the total number of results still respects the limit you asked for.