Configure Algolia Custom Ranking to Boost Records by a Numeric Attribute

Desired outcome

Adjust Algolia’s ranking so that records with higher values of a chosen numeric attribute (e.g., popularity_score or profit_margin) appear earlier in search results, while still letting textual relevance decide the order when those numeric values are equal.

Prerequisites

• An active Algolia application with at least one index.
• The index already contains a numeric attribute you want to use for custom ranking (e.g., popularity_score of type integer or float).
• An API key that includes the editSettings permission (usually an Admin key or a key with custom ACL).
• Access to the Algolia Dashboard or ability to call the Settings API.

Procedure

1. Open the index settings

   In the Algolia Dashboard, select your application, then the target index. Choose Ranking from the left‑hand menu.

2. Add the custom attribute

   Under the Custom ranking section, click Add an attribute. Type the exact name of the numeric attribute (case‑sensitive).

   After it appears in the list, use the drag handle to set its position. For higher values to rank better, place the attribute above the default textual ranking criteria and ensure the ordering is set to descending (the default for numeric attributes). If you want lower values to rank better, choose ascending from the dropdown that appears when you hover the attribute.

3. Save the change

   Click Save changes. Algolia applies the new ranking immediately to incoming queries.

4. Ensure the attribute is present in records

   If the attribute is missing from some records, those records will be treated as having a null value and will be ranked according to the remaining criteria. To guarantee the attribute exists, reindex your data after adding the attribute to your source.

   Example reindex using the Algolia CLI (replace placeholders):

   algolia index:copy YOUR_SOURCE_INDEX YOUR_TARGET_INDEX --scope=settings
   

5. Verify the impact

   Run the same search query before and after the change and compare the position of a known record with a high custom‑ranking value.

   Using the Search API (curl example):

   curl -X GET \
        "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/YOUR_INDEX_NAME/query" \
        -H "X-Algolia-Application-ID: YOUR_APP_ID" \
        -H "X-Algolia-API-Key: YOUR_ADMIN_KEY" \
        -d '{"query":"your search term","hitsPerPage":10}'
   

   In the Dashboard, open the Search Tester, enable the Explain toggle, and inspect the score breakdown to confirm that the custom attribute contributes to the total ranking score.

Expected checks

• Perform a search query (e.g., "laptop") and note the rank of a record with a high popularity_score.
• Apply the custom ranking as described, then repeat the same query.
• Verify that the record with the higher popularity_score moves upward in the hits list.
• When two records have identical custom‑ranking values, ensure their order follows textual relevance (the default ranking criteria).
• Check that no errors appear in the API response; a successful response returns {"status":200,"message":"OK"} after saving settings.

Recovery options

• Remove the custom attribute: Return to the index → Ranking → Custom ranking screen, click the trash icon next to the attribute, and save. The index reverts to the previous ranking order.
• Reset all settings: In the Dashboard, go to Settings → Reset all settings. This restores ranking, faceting, and other parameters to their defaults. Use this only if you need a clean slate, as it will erase any custom configuration you may have added.
• Reindex if needed: After reverting ranking, you may want to reindex to ensure any temporary changes to records (e.g., added fields for testing) are removed.