Bucket sort

How Meilisearch uses bucket sort to rank search results through sequential ranking rules.

Meilisearch uses bucket sort to rank search results. This algorithm distributes documents into buckets based on ranking rules, then recursively sorts within each bucket using subsequent rules.

How bucket sort works in Meilisearch

When you search, Meilisearch doesn’t score documents with a single number. Instead, it applies ranking rules sequentially, sorting documents into buckets at each step.

Example: Searching for “Badman dark knight returns”

Step 1: Apply the words rule

The first ranking rule (words) sorts documents by how many query words they contain:

Bucket	Matches	Documents
1	All 4 words	”Batman: The Dark Knight Returns”
2	3 words	”Batman: The Dark Knight”
3	2 words	…
4	1 word	”Angel and the Badman”

Step 2: Apply the typo rule within buckets

If a bucket contains multiple documents, the next rule (typo) breaks ties. For example, in the 1-word bucket where “Badman” appears:

Bucket	Typos	Documents
4.1	0 typos	Documents containing “Badman” exactly
4.2	1 typo	Documents corrected “Badman” → “Batman”

This continues recursively until all buckets contain single documents or all ranking rules are exhausted.

Why bucket sort?

Bucket sort offers several advantages for search ranking:

1. Flexibility: Different sorting algorithms can be applied within individual buckets
2. Configurable priority: You control which criteria matter most by reordering rules
3. Efficient tie-breaking: Only documents that tie on one rule need evaluation by the next

Best and worst cases

Case	Condition	Complexity
Best	Documents spread evenly across buckets	O(n+k) where n=documents, k=buckets
Worst	All documents in one bucket	Depends on the sorting algorithm used

Default ranking rules

Meilisearch applies these rules in order:

1. words: Documents containing more query words rank higher
2. typo: Documents with fewer typos rank higher
3. proximity: Documents where query words appear closer together rank higher
4. attributeRank: Documents matching in more important attributes rank higher
5. sort: User-defined sort order (if specified)
6. wordPosition: Documents with matches closer to the beginning of an attribute rank higher
7. exactness: Documents with exact matches rank higher

Customizing ranking rules

You can reorder, add, or remove ranking rules:

curl -X PUT "${MEILISEARCH_URL}/indexes/movies/settings/ranking-rules" \
  -H "Authorization: Bearer ${MEILISEARCH_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '[
    "words",
    "typo",
    "proximity",
    "attributeRank",
    "sort",
    "wordPosition",
    "exactness",
    "release_date:desc"
  ]'

Adding release_date:desc as a custom rule means newer movies rank higher when all other factors are equal.

Related concepts

• Ranking rules: Configure ranking behavior
• Ranking score: Understanding search relevance scores
• Custom ranking rules: Add business logic to ranking