Boosting Best‑Sellers with Algolia Custom Ranking: A Practical Guide

The problem: relevance vs. business priority

When users search for a product, Algolia’s default ranking tries to return the most textually relevant results. In an e‑commerce catalog, however, you often want the best‑selling items to appear first, even if another product matches the query wording slightly better. Relying solely on textual relevance can bury popular items, while forcing popularity to dominate can hurt long‑tail queries.

Thesis: Custom Ranking lets you blend a business metric with Algolia’s relevance score

Algolia’s ranking formula is a list of criteria applied in order. After the built‑in textual match factors (typo, geo, words, filters, proximity, attribute, exact) are evaluated, you can insert up to five custom criteria. Each custom criterion is a numeric attribute you define, sorted ascending or descending. The attribute does not change the textual match score; it only re‑orders records that are otherwise tied on the earlier criteria.

Section 1: How the ranking formula works

The default ranking array looks like this:

["typo","geo","words","filters","proximity","attribute","exact"]

Adding a custom criterion inserts it after the built‑in factors. For example, to promote products with higher sales, you would extend the array:

["typo","geo","words","filters","proximity","attribute","exact","custom(sales_count desc)"]

The desc modifier tells Algolia to sort the sales_count attribute in descending order.

Section 2: Configuring Custom Ranking via the Dashboard or API

In the Algolia Dashboard:

1. Open your index → Ranking → Custom Ranking.
2. Click Add an attribute, select sales_count, and choose Descending.
3. Save changes.

Using the API (replace YOUR_APP_ID, YOUR_ADMIN_KEY, and your_index with your values):

# Pseudo‑code; run in a terminal with curl or your preferred client
curl -X PUT \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/your_index/settings" \
  -H "X-Algolia-Application-ID: YOUR_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_KEY" \
  -d '{"customRanking":["desc(sales_count)"]}'

This call overwrites the entire ranking array; Algolia merges your custom list with the default built‑in factors automatically.

Section 3: Worked example

Assume an index products with three records:

objectID	name	description	sales_count
1	Running Shoe A	Lightweight trail shoe	150
2	Running Shoe B	Lightweight trail shoe	300
3	Running Shoe C	Lightweight trail shoe	75

All three records have identical textual match for the query "running shoes" (same typo, geo, words, etc.). After applying the default ranking, their order is determined by the custom criterion sales_count desc. The result set will be:

1. Running Shoe B (sales_count = 300)
2. Running Shoe A (sales_count = 150)
3. Running Shoe C (sales_count = 75)

If you removed the custom ranking, the order would revert to the default tie‑breaking rule (usually by objectID), which may not reflect business priority.

Trade‑off and limitation

Adding a strong custom ranking can diminish relevance for niche queries where the business metric does not correlate with user intent. For example, a query for "vintage running shoes" might still return a newly released best‑seller if sales_count outweighs textual match. Additionally:

• Only five custom slots are available; you must choose the most impactful attributes.
• Changing the custom ranking forces a full reindex of all records, which can cause temporary latency.
• The attribute must be kept up‑to‑date; stale sales counts will promote outdated items.

Actionable closing: test, monitor, and refresh

1. Create a test index and add a few records with a numeric popularity field.

2. Apply the custom ranking via the Dashboard or API as shown above.

3. Run a search query and verify that higher‑popularity records appear earlier while the textual match score (visible in the _rankingInfo field) remains unchanged.

4. Use index.getSettings() to confirm the customRanking array contains "desc(sales_count)".

5. Schedule a regular refresh of the sales_count attribute (e.g., nightly batch) to keep the ranking current.

By following these steps you can surface best‑selling products without sacrificing the core relevance that Algolia provides.