Configure Algolia Custom Ranking to Prioritize High‑Stock and Promoted Products

Desired outcome

Adjust Algolia’s ranking so that products with higher inventory levels and active promotions are returned before items that are low in stock or not promoted. This tends to improve conversion because shoppers see purchasable goods first.

Prerequisites

• An Algolia application with at least one index that stores product records (e.g., products).
• API credentials: Application ID and Admin API Key (required to modify index settings and push records).
• The Algolia client library installed in your backend language. The examples below use Node.js (≥14) with the algoliasearch package, but the same concepts apply to Python, Java, etc.
• Basic familiarity with JSON record structure and terminal/command‑line usage.

Procedure

1. Add custom ranking attributes to the index settings

   Open a terminal where you can run Node.js scripts with your Algolia credentials available as environment variables (ALGOLIA_APP_ID and ALGOLIA_ADMIN_KEY).

   // update-settings.js
   const algoliasearch = require('algoliasearch');
   
   const client = algoliasearch(
     process.env.ALGOLIA_APP_ID,
     process.env.ALGOLIA_ADMIN_KEY
   );
   const index = client.initIndex('products');
   
   // Define custom ranking: higher stock and higher promoScore first
   const settings = {
     customRanking: ['desc(stock)', 'desc(promoScore)']
   };
   
   index.setSettings(settings).then(() => {
     console.log('Custom ranking updated');
   }).catch(err => {
     console.error('Failed to update settings:', err);
   });
   

   Run the script:

   node update-settings.js
   

   Required permission: Admin API Key (allows setSettings). Changing settings triggers a background reindex; expect a brief increase in latency and operation unit usage.

2. Ensure records contain the new numeric attributes

   Each product record must have a numeric stock (e.g., units available) and a numeric promoScore (higher for active promotions). If a record lacks the attribute, Algolia treats it as 0 for ranking, which may push the item down unintentionally.

   Example partial update for a single product (objectID 12345):

   // partial-update.js
   const algoliasearch = require('algoliasearch');
   
   const client = algoliasearch(
     process.env.ALGOLIA_APP_ID,
     process.env.ALGOLIA_ADMIN_KEY
   );
   const index = client.initIndex('products');
   
   const update = {
     objectID: '12345',
     stock: 150,          // units in inventory
     promoScore: 8        // 0‑10 scale, higher = stronger promo
   };
   
   index.partialUpdateObject(update, { createIfNotExists: false }).then(() => {
     console.log('Record updated');
   }).catch(err => {
     console.error('Update failed:', err);
   });
   

   Run:

   node partial-update.js
   

   Required permission: Admin API Key (or a Search‑Only key with addObject permission if using saveObject).

3. Reindex or rely on partial updates

   If you added the attributes to many records, consider a full reindex from your source data. For incremental changes, the partial update approach above is sufficient and avoids downtime.

4. Verify the impact
   1. Open the Algolia Dashboard → Index → Configuration → Ranking and sorting. Confirm that customRanking shows desc(stock) and desc(promoScore).
   2. Use the Dashboard’s Search Tester or run a query via the API with the analytics tag to inspect the _rankingInfo field:

   // verify-query.js
   const algoliasearch = require('algoliasearch');
   
   const client = algoliasearch(
     process.env.ALGOLIA_APP_ID,
     process.env.ALGOLIA_ADMIN_KEY
   );
   const index = client.initIndex('products');
   
   index.search('phone', { analytics: true, analyticsTags: ['test'] }).then(({ hits }) => {
     hits.forEach(h => {
       console.log(`ID: ${h.objectID}, stock: ${h.stock}, promoScore: ${h.promoScore}`);
       console.log('  _rankingInfo:', h._rankingInfo);
     });
   }).catch(err => {
     console.error('Query error:', err);
   });
   

   Run:

   node verify-query.js
   

   Look for non‑zero contributions from the stock and promoScore criteria in _rankingInfo. Higher values should push those hits toward the top of the list.

Expected checks

• Custom ranking appears under Index → Configuration → Ranking and sorting.
• Test queries return _rankingInfo with entries for stock and promoScore.
• Comparing result order before/after the change (using a set of representative queries) shows higher‑stock/promo items moving upward.

Limitations

• Custom ranking only works with numeric (integer or float) or boolean attributes. Strings, arrays, or missing values are ignored for ranking.
• Changing index settings triggers a reindex; during this period query latency may rise and operation units are consumed. Schedule changes during low‑traffic windows.
• If many records lack the new attributes, they will be ranked as if the value were zero, potentially demoting legitimate products. Ensure data completeness before enabling the ranking.

Practical way to check the result

After updating records, run a batch of queries that represent typical shopper intent (e.g., "running shoes", "wireless headphones"). Export the top‑5 hits for each query before and after the change (you can log the objectID values). Verify that the average position of high‑stock/promo items improves.

Recovery options (rollback)

If the new ranking produces undesirable results:

1. Remove the added criteria from custom ranking:

// revert-settings.js
const algoliasearch = require('algoliasearch');

const client = algoliasearch(
  process.env.ALGOLIA_APP_ID,
  process.env.ALGOLIA_ADMIN_KEY
);
const index = client.initIndex('products');

index.setSettings({ customRanking: [] }).then(() => {
  console.log('Custom ranking reset to default');
}).catch(err => {
  console.error('Reset failed:', err);
});

Run:

node revert-settings.js

1. Optionally, delete the stock and promoScore attributes from records if they are no longer needed (using a partial update with null or the deleteObject method).
2. Reindex or let the existing records propagate; the ranking will revert to the previous ordering (typically textual relevance, popularity, or any other custom ranking you had before).

Required permission: Admin API Key. No data loss occurs; only ranking behavior changes.

---

By following these steps you can tune Algolia’s search results to favor products that are more likely to convert, while retaining a clear path to revert the change if needed.