Meilisearch v0.29 is out and comes with a new feature: matching strategy customization!

Consider the following situation: a user sends a two-word search request. What happens when there are not enough documents to meet the requested limit? Should the engine only return documents with all the query terms? Or should it return more documents? If so, which criteria should it apply to return them?

That’s where  matching strategies come in. A matching strategy is used to match query terms when the engine has not found enough documents containing all query terms. It’s not an easy decision to make, and it’s highly dependent on the type of data the user is searching for. Fortunately, now you can choose the strategy to apply at search time 🎉

A little bit of history

Back in 2021, all versions pre v0.21 only returned documents where all the query terms were present. So if I searched for “Peter Parker”, it would just return documents in which both terms —“peter” and “parker”— were present. This matching strategy is called: all because all query terms must be present in the document for it to be returned.

You're welcome GIF

Ranking rules are one of Meilisearch’s most important features for  ensuring relevant results. The words ranking rule states the following:

Results are sorted by decreasing number of matched query terms. Returns documents that contain all query terms first.

This rule had been lying around in our documentation for a while, coupled with the following warning message:

For now, it is mandatory that all query terms are present in returned documents. Therefore, this rule does not impact search results yet.

With v0.21, the words rule started working, so this warning disappeared with the all-query-terms-present constraint.

From that point on, if there were not enough documents containing all query terms, Meilisearch removed one term at a time, starting from the end of the query. So if I searched for “Peter Parker”, it would first return documents in which both terms were present, followed by documents with just “Peter”

This type of matching strategy is called last because Meilisearch removes the last term of the query.

Nailed it GIF

It turned out that many users were pretty content with the previous matching behavior. Unfortunately, this change did not allow them to migrate to a newer version of Meilisearch, which prevented them from benefiting from its many improvements: sorting at search time, geosearch, granular API keys rights, multi-tenancy, etc. Not only were they missing all that, but they were going to miss all the awesome features to come! 😱

Don’t panic! Version 0.29 has come to the rescue!

Closing the feedback loop

Now, it’s possible to choose your desired matching strategy at search time. The default strategy is last; if you want to use all, all (wink wink) you need to do is specify it in the search body as follows:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "peter parker", "matchingStrategy": "all" }'

This feature has been in the works since September 2021, when Guillaume Mourier, our Product Manager, started the “Policy for matching query words” discussion to collect feedback on the matter. We would like to thank everyone involved for taking the time to share their input 🙏 Meilisearch would not exist as it does today without the support from our community 🥰

There are as many reasons to use either strategy as there are many use cases. Not sure yet which one to choose? I’ve created a demo so you can test both strategies to help you make up your mind 😊

For more in-depth information on matching strategy customization, you can read the dedicated section of the documentation.

The demo

This demo uses the movies dataset, used in Meilisearch’s quick start guide and widely throughout the documentation.

I have made no changes whatsoever to the settings. I have simply indexed the dataset and have kept the default configuration. Pure as the driven snow ❄️

When performing a search, you can click on the button to modify the matchingStrategy search parameter and see the different results depending on the strategy used.

Try it here 👉

If you lack ideas or need some inspiration for query terms, I have listed some query ideas, ranging from 2 to 10-word queries:

  • forrest gump
  • big fat liar
  • return to never land
  • the purple rose of cairo
  • the curious incident of the dog in the night time
When searching for "the hateful eight", Meilisearch finds 28412 results with the "last" matching strategy versus one result with the "all" matching strategy


I hope this demo has helped you better comprehend the differences between the two strategies and their impact on search results. As usual, you can find the code on GitHub.

There are numerous ways of fine-tuning the relevancy of your search results. This is just one of the many options available. We know every project is different and has its own requirements; that’s why your feedback is so important to us. We work to make it easy to customize your instance so that you can deliver the best search experience to your users.

Don’t hesitate to check our product repo and make a suggestion or join an existing discussion on improving the product.

If you like Meilisearch and want to support us, a star on GitHub means a lot 😇