Are you returning the search results your users want?

Meilisearch lets you choose, at search time, how strictly a query has to match a document. That setting is the matching strategy, and it changes how many results a search returns and how relevant they are.

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 decides what the engine does when it has not found enough documents containing all the query terms. It’s not an easy decision, and it depends heavily on the kind of data being searched, which is why you can choose the strategy per search request.

Why matching strategies exist

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

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.

It turned out that many users were pretty content with the previous matching behavior. Unfortunately, that change stopped them from moving to a newer version of Meilisearch, and so from picking up everything that came with it: sorting at search time, geosearch, granular API key rights, multi-tenancy, and more.

Making the strategy configurable per request resolved that.

Choosing a matching strategy at search time

You set the strategy per request with the matchingStrategy search parameter. The default is last. To use all, pass it in the search body:

The three strategies

• last (default): returns documents containing all query terms first. If there are not enough, Meilisearch removes one term at a time starting from the end of the query, so "big fat cat" becomes "big fat", then "big".
• all: only returns documents containing every query term. Meilisearch never relaxes the query, even if that means returning fewer results than the limit.
• frequency: also returns documents containing all query terms first, but when it relaxes the query it drops the term that is most common in your dataset, keeping the rarer and more distinguishing ones. Searching "white cotton shirt" in a catalogue full of shirts will prioritize "white" and "cotton" over "shirt".

frequency is usually the better default for catalogues where one term appears in most documents, because last would otherwise discard whichever meaningful word happened to be typed last.

This feature grew out of a community discussion started in September 2021 by Guillaume Mourier, the “Policy for matching query words” discussion, which collected feedback on how the engine should behave.

Not sure which one to choose? There is a demo below so you can compare them on real data.

Comparing the strategies on real data

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

No settings were changed. The dataset is indexed with the default configuration.

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: matching-strategy.meilisearch.com

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

Conclusion

I hope the demo has clarified how the strategies differ and what they do to your result set. 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.

Matching strategy is one setting among many. If you would rather not tune infrastructure alongside relevancy, Meilisearch Cloud runs the engine for you, with a 14-day free trial and no credit card required.

Don’t hesitate to check our product discussions to make a suggestion or join an existing thread.

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

Frequently asked questions (FAQs)

What is a matching strategy in Meilisearch?

A matching strategy tells Meilisearch what to do when it cannot find enough documents containing every term of a query. It either relaxes the query by dropping terms, or refuses to and returns fewer results. You set it per search request with the matchingStrategy parameter.

What is the difference between the last, all, and frequency strategies?

last drops query terms from the end until it has enough results. all never drops terms, so it returns only documents matching the full query. frequency drops the term that occurs most often in your dataset first, which keeps the rarer, more distinguishing words in play. The default is last.

Which matching strategy should I use?

Use all when precision matters more than recall and an empty result set is an acceptable answer, such as a parts catalogue with exact reference numbers. Use frequency for product catalogues where a common word like "shirt" appears in most documents. Keep the default last when queries read as natural phrases and the important words tend to come first.

Does the matching strategy change how results are ranked?

It changes which documents are eligible, not how the eligible ones are ordered. Meilisearch still applies its ranking rules as a bucket sort, and documents matching all query terms are still returned ahead of documents matching only some.