Boosting Search with Algolia’s Custom Ranking: A Practical Guide

Problem: The Search‑Relevance Gap in E‑Commerce

When customers type a keyword, the first few hits they see are usually the most lexically relevant. That’s great for a search engine, but for an online store you also want to surface products that are in stock, high‑margin, or trending. The challenge is to influence the order of results without rewriting your entire search pipeline.

Solution: Algolia’s Custom Ranking Feature

Algolia lets you attach numeric scores to any attribute in your records—think popularity, profit_margin, or stock_level. These scores are combined with the default textual relevance to produce the final ranking. The feature is configured in the dashboard or via the API, and it works seamlessly with typo tolerance, faceting, and geo‑search.

How Custom Ranking Works Under the Hood

1. Textual Relevance is computed first. Algolia assigns a score based on how well the query words match the record’s searchable attributes.

2. Custom Ranking Scores for each listed attribute are normalized to a 0‑1 range. The order you list them in the dashboard determines their weight hierarchy.

3. The final score is a weighted sum of textual relevance and custom ranking values. Records with identical textual relevance are then sorted by the custom ranking.

Setting Up Custom Ranking in the Dashboard

Navigate to Ranking > Custom Ranking and add your attributes. For example:

1. desc(popularity)
2. desc(stock_level)
3. asc(price)

Algolia normalizes each attribute. If popularity ranges from 0 to 10,000, the algorithm maps 10,000 to 1.0 and 0 to 0.0 before applying the weight.

Worked Example: Prioritizing Fast‑Moving Inventory

Suppose you have the following three products indexed:

Product ID	Name	popularity	stock_level	price
101	Wireless Mouse	8500	120	25.99
102	Wireless Mouse	4200	15	24.99
103	Wireless Mouse	3000	200	26.49

All three match the query “wireless mouse” with identical textual relevance. With the custom ranking above, Algolia will order them as follows:

1. Product 101 (high popularity, moderate stock)
2. Product 103 (moderate popularity, high stock)
3. Product 102 (low popularity, low stock)

Result: The best‑selling item appears first, followed by the well‑stocked variant, keeping low‑performing SKUs from cluttering the top.

Verifying the Impact with the Search Tester

1. Open the Algolia dashboard, select your index, and click Search Tester.

2. Enter a query (e.g., “wireless mouse”).

3. Click the Explain button. You’ll see a breakdown for each hit:

{
  "_rankingInfo": {
    "textualRelevance": 0.98,
    "customRanking": 0.76,
    "finalScore": 0.95
  }
}

4. Compare the customRanking values before and after adding the popularity attribute to confirm the shift.

Trade‑Offs and Limitations

• Limited to Ties: Custom ranking only reorders records that have the same textual relevance. A record with a markedly better keyword match will stay ahead regardless of custom score.
• Potential for Homogenization: Over‑weighting a single attribute can bury niche items. Balance custom ranking with diverse business signals to maintain long‑tail discoverability.
• Normalization Caveat: Each attribute is rescaled to 0‑1. If your data has outliers, the scaling may compress the useful range. Consider normalizing your data before indexing.

Actionable Checklist

1. Identify business metrics you want to influence (e.g., popularity, stock, profit margin).
2. Add those metrics to your records and ensure they’re numeric.
3. Configure the Custom Ranking list in the dashboard or via the API.
4. Use the Search Tester or getRankingInfo to verify the ranking shift.
5. Monitor CTR and conversion data to confirm that the new order improves business outcomes.
6. Periodically re‑evaluate the weights to adapt to changing business priorities.

Conclusion

Algolia’s custom ranking gives you a powerful, low‑friction way to inject business logic into search relevance. By carefully selecting attributes, validating with the Explain panel, and monitoring real‑world metrics, you can keep your product catalog both relevant and profitable without overhauling your search architecture.