Using Algolia Custom Ranking to Boost Business Metrics Without Losing Relevance

Problem: Pure textual relevance can hide profitable items

When Algolia ranks records, the default formula looks only at how well the query matches the text in each record. If two products have the same textual score, their order is arbitrary. This means a high‑margin, best‑selling item can appear below a low‑stock, low‑rated counterpart simply because the words match equally well.

Thesis: Custom Ranking lets business metrics act as tie‑breakers

Algolia’s customRanking setting adds one or more attributes (e.g., rating, stock) that are evaluated after the textual relevance score. When the textual scores are identical, the custom attributes decide the order, letting you promote items that are more popular, profitable, or available without overriding keyword relevance.

How Custom Ranking works

Algolia computes a relevance score for each record based on the query. Records are first sorted by that score. If two or more records share the exact same score, Algolia evaluates the customRanking list in order:

1. Each entry is a string like "desc(rating)" (descending) or "asc(price)" (ascending).
2. The first attribute that differs between the records determines the final order.
3. If all custom attributes are equal, the original tie‑breaker (objectID) is used.

Because custom ranking is only a tie‑breaker, a record with a higher textual relevance will always outrank a record with a lower score, regardless of its business metrics.

Configuring Custom Ranking

Via the Dashboard

1. Open the Algolia Dashboard and select your index.
2. Navigate to Ranking and Sorting → Custom Ranking.
3. Click Add an attribute, type the attribute name, choose Descending or Ascending, and save.
4. The UI instantly shows the updated list, e.g., ["desc(rating)", "desc(stock)"].

Via the API (requires an Admin API key)

# Replace placeholders with your values
INDEX_NAME=""
ADMIN_KEY=""

# Get current settings
curl -s -X GET \
  "https://-dsn.algolia.net/1/indexes/${INDEX_NAME}/settings" \
  -H "X-Algolia-API-Key: ${ADMIN_KEY}" \
  -H "X-Algolia-Application-ID: "

# Update custom ranking
curl -s -X PUT \
  "https://-dsn.algolia.net/1/indexes/${INDEX_NAME}/settings" \
  -H "X-Algolia-API-Key: ${ADMIN_KEY}" \
  -H "X-Algolia-Application-ID: " \
  -H "Content-Type: application/json" \
  -d '{"customRanking":["desc(rating)","desc(stock)"]}'

After a PUT request, Algolia applies the new setting immediately; however, if you change which attributes are used, you must re‑index the records so the new attribute values are searchable. Frequent changes can increase indexing latency and cost.

Worked example: e‑commerce index

Suppose an index contains two records:

• Record A: { "name": "Wireless Headphones", "rating": 4.8, "stock": 120 }
• Record B: { "name": "Wireless Headphones", "rating": 4.2, "stock": 30 }

A user searches for "wireless headphones". Both records receive the same textual relevance score because the query matches the name exactly. With customRanking = ["desc(rating)", "desc(stock)"]:

1. Algolia compares the rating values: 4.8 > 4.2, so Record A wins.
2. If the ratings were equal, it would fall back to stock (higher stock first).

Thus the higher‑rated, higher‑stock item appears first, increasing the chance of a sale while still honoring the keyword match.

Trade‑off and limitation

Over‑emphasizing custom ranking can hurt relevance for long‑tail or niche queries where textual differences are subtle. If the custom attributes dominate the tie‑breaker, a less‑relevant item may appear before a better‑matching one simply because it scores higher on the business metric.

To mitigate this:

• Monitor click‑through rate (CTR) and conversion rate after each change.
• Adjust the order or drop attributes if you see a decline in relevance‑driven metrics.
• Consider using rankingFormula (if available) to weight textual score versus custom attributes, rather than relying solely on tie‑breaking.

Practical verification steps

1. Create two test records with identical searchable fields but different values for your custom attribute (e.g., rating).
2. Run a search query that matches both records exactly (e.g., the product name).
3. Check the returned order: the record with the higher custom‑ranked attribute should appear first.
4. In the Dashboard, verify the setting under Ranking and Sorting → Custom Ranking.
5. Via API, call getSettings and confirm the customRanking array matches your configuration.

If the order is not as expected, re‑index the records to ensure the custom attribute values are searchable, then repeat the test.

Actionable closing

Start small: add one business metric as a descending custom ranking, run the verification test above, and watch your core search metrics. If CTR or conversion improves, consider adding a second metric; if relevance suffers, revert the change (update customRanking and re‑index). By treating custom ranking as a controlled experiment, you can let profitability guide the results without sacrificing the core promise of Algolia’s relevance engine.