Tuning Meilisearch ranking rules: a visual walkthrough

Meilisearch ranks search results using six rules applied in order: words, typo, proximity, attribute, sort, exactness. Each rule sorts the result set; ties are broken by the next rule. Reordering or removing rules is the single highest-leverage relevance lever Meilisearch gives you.

The 30-second answer

The default order is correct for ~80% of search use cases. Reorder it when you have a specific business priority that the defaults don't match — e-commerce sorting by price, news sorting by date, documentation prioritising exact heading matches.

The six default rules, in order

1. words

Documents containing more of the searched query terms rank higher. If a user searches "red running shoes", a document containing all three words beats a document containing only two.

2. typo

Documents with fewer typos relative to the query rank higher. A document matching "running" with no typos beats one matching "runnig" (one typo). See our typo tolerance guide for the configuration knobs.

3. proximity

Documents where the matched terms appear closer together rank higher. "Red running shoes" beats "running shoes that are red" for the same query because the matched words are adjacent.

4. attribute

Documents where the match appears in a higher-priority attribute rank higher. The priority is determined by the order of searchableAttributes: matches in the first attribute outrank matches in the second, and so on. Default is "all attributes equal" — you set the priority explicitly.

5. sort

If the query specifies a sort parameter, this rule applies it. The sort attribute must be in the index's sortableAttributes list. Without a sort param the rule is a no-op.

6. exactness

Documents where the matched word is exactly the search term (not a prefix match) rank higher. "Run" exactly matches "run" but only prefix-matches "running" — the exact match wins.

Reorder them when

E-commerce: sort by price as a tiebreaker

Default order works well for e-commerce except when two products are equally relevant and you want the cheaper one to win. Move sort earlier in the list (e.g. before proximity) and pass sort=price:asc at query time.

News / blog search: recency wins

For news content, "newer beats older" almost always trumps text relevance for the same query. Add a custom rule:

[
  "words",
  "typo",
  "desc(published_at)",
  "proximity",
  "attribute",
  "exactness"
]

This re-sorts the result set by descending publish date after the first two rules have done their work.

Documentation: exactness wins

For documentation search, an exact heading match almost always beats a prefix match elsewhere. Move exactness earlier:

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

Geosearch: distance wins

If you're doing location-based search (restaurants, real estate), you almost always want closer-to-the-user beats more-relevant text. Add a geo rule:

[
  "words",
  "typo",
  "_geoPoint(lat, lng):asc",
  "proximity",
  "attribute",
  "exactness"
]

Custom ascending and descending rules

Beyond the six built-in rules, Meilisearch accepts custom rules of the form asc(attributeName) or desc(attributeName). The attribute must be numeric and listed in sortableAttributes. These let you bake business priorities into the ranking pipeline (popularity score, manual featured-product weight, recency, etc.).

How to test ranking changes

1. Make the change in a non-production environment first.
2. Run the same set of test queries before and after.
3. Compare the top 10 results. Are the changes intentional?
4. Run the change against production read traffic for a few hours and watch your zero-result rate (it shouldn't increase).
5. Promote to production.

Reordering ranking rules is reversible — Meilisearch reindexes within seconds for most index sizes, and rolling back is one more PATCH.

What NOT to do

• Don't remove words or typo. They're load-bearing for any user-facing search. The relevance falls off a cliff without them.
• Don't add more than 8 rules total. Ranking is applied per query, so each extra rule slows search down. The default six are tuned for performance.
• Don't sort by a non-numeric attribute. Custom asc() / desc() rules require numeric values.

FAQ

What's the difference between ranking rules and the sort parameter?

Ranking rules are baked into the index settings and apply to every query. The sort parameter is per-query. The sort ranking rule (rule #5 by default) is what applies the per-query parameter — without it in the rules list, the parameter does nothing.

Can I have different ranking rules per query?

Not directly — ranking rules are an index-level setting. If you need very different ranking for different query types, the workaround is to maintain multiple indexes with the same documents but different settings, and route the query to the right one in your application.

How do I see which ranking rule is responsible for a result's position?

Pass showRankingScoreDetails=true at query time. Meilisearch will return per-rule contributions to the final ranking score for each hit. This is the fastest way to debug "why is this result ranked here?" questions.

Can AdminDex help with ranking rules?

Yes — AdminDex's settings editor has a drag-and-drop ranking-rule reorder UI with inline help for each rule. Reordering is a single click instead of a hand-edited PATCH request.