Balancing Business Goals and Text Relevance with Algolia Custom Ranking

Your search index returns exact keyword matches, but the order feels wrong. A query for "running shoes" surfaces a discontinued clearance model before your best-selling current release. The problem is not relevance—it is that Algolia's textual scoring does not know which record matters more to your business. Custom ranking fixes this by letting you layer business attributes on top of keyword matching, but only if you use it as a tie-breaker rather than a replacement for relevance.

How custom ranking fits into the ranking formula

Algolia computes a textual relevance score first. This score reflects how well a record matches the query terms, including typos, proximity, and attribute importance. Custom ranking runs after that score. It does not change whether a record matches; it changes the order among records that already match.

You configure custom ranking as an ordered list in your index settings. Each entry is an attribute name prefixed with asc or desc. Algolia normalizes each attribute to a 0–1 range, applies the direction, and combines the values with a weighted sum. The attribute that appears first in the list has the most influence on ties.

The feature works with numeric, boolean, and string attributes. Numeric attributes like popularity or stock_level are straightforward. Strings are compared lexicographically after normalization, which is useful for categorical sorting like brand or category, but it follows character-code order rather than human alphabetical intuition.

A worked example: e-commerce index settings

Suppose you want best-selling, newer products to appear first when textual scores are equal. Apply the following JSON payload to your index settings from your server or the Algolia dashboard using an Admin API key or a key with the editSettings ACL.

{
  "customRanking": [
    "desc(popularity)",
    "desc(release_date)"
  ]
}

Replace YOUR_INDEX_NAME, YOUR_APP_ID, and YOUR_ADMIN_API_KEY with your actual values. After the update, search for a term where multiple records have similar textual scores and verify that higher popularity values appear first. The setting change itself is instantaneous, but if you later change the underlying attribute values, those records must be reindexed.

Risk: If popularity is missing or zero for some records, they will be pushed down. Make sure the attribute is populated for all records you want to rank competitively.

Diagnosing the balance with explain

Before shipping a change, use the explain parameter to see how Algolia arrived at the order. Set explain to true in your search parameters. The response includes a breakdown of the textual score and each custom ranking component, letting you verify the contribution of each attribute.

{
  "query": "running shoes",
  "explain": true
}

Run this from any Algolia API client with a search-only API key. Inspect the returned score components. If a record with a weak textual match is ranking highly, its custom ranking contribution is too strong. Reduce the weight or move the attribute lower in the list.

Trade-offs and limitations

The biggest risk is drowning out textual relevance. If you weight popularity too heavily, an unrelated bestseller can outrank a precise keyword match. Custom ranking is a tie-breaker, not a relevance engine.

String attributes have a subtle limitation: lexicographic comparison after normalization means "BrandA" and "branda" may not sort the way you expect. Test with real data before relying on string custom ranking.

Finally, measure the business impact. Use the Algolia Analytics dashboard to run A/B tests comparing click-through rates before and after the change. A custom ranking formula that improves conversion without hurting search success is the goal.

Actionable next step

Pick one business attribute that matters most—usually popularity or recency. Add it as desc(attribute) to your custom ranking list. Preview the effect in the dashboard's Ranking and Sorting section, then run a search with explain set to true to confirm the textual score is still doing the heavy lifting. If the balance looks wrong, remove the attribute or revert to the previous list; the setting update is instantaneous. Only when the preview and diagnostics look right should you roll the setting out to production.