Using Algolia Query Rules to Promote Records Based on Search Terms

Quick answer

You can make Algolia boost specific records when a search query contains a particular word or phrase by creating a Query Rule. The rule’s condition looks for the keyword in the query text, and its consequence promotes the chosen objectID to a fixed position in the results.

How the mechanism works

When a search request arrives, Algolia evaluates all Query Rules for the target index in the order they were created (unless you set an explicit ranking). If a rule’s condition matches the request, its consequence is applied before the regular ranking formula. A typical use‑case is to promote a product when the user types a promotional term like “sale”.

Worked example: promote a product for queries containing “sale”

1. Ensure you have an index named products that already contains the record you want to promote, e.g. objectID 12345.
2. Create the rule via the Algolia Admin API. Replace the placeholders with your own values:

curl -X POST \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/products/rules" \
  -H "Content-Type: application/json" \
  -H "X-Algolia-Application-ID: YOUR_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_API_KEY" \
  -d '{
    "objectID": "promote-sale-rule",
    "condition": {
      "pattern": "sale",
      "anchoring": "contains"
    },
    "consequence": {
      "promote": [
        {
          "objectID": "12345",
          "position": 1
        }
      ]
    }
  }'

The anchoring parameter is critical: contains means the rule triggers if the query string includes the pattern anywhere. Omitting it defaults to is, which would only match an exact query of “sale” and likely cause the rule to never fire.

Verifying the rule works

Perform a search that matches the condition and inspect the response:

curl -X GET \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/products/query?x-algolia-application-id=YOUR_APP_ID&x-algolia-api-key=YOUR_SEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":"query=summer sale"}'

Check the hits array: the object with objectID: "12345" should appear at index 0 (position 1). If it does not, re‑fetch the rule to confirm its definition:

curl -X GET \
  "https://YOUR_APP_ID-dsn.algolia.net/1/indexes/products/rules/promote-sale-rule" \
  -H "X-Algolia-Application-ID: YOUR_APP_ID" \
  -H "X-Algolia-API-Key: YOUR_ADMIN_API_KEY"

Limits and practical considerations

• Rule count: Each index can store up to 10,000 Query Rules. Exceeding this limit returns an error when creating a new rule.
• Latency impact: Simple conditions (single pattern, contains/is/startsWith) add negligible overhead. Complex conditions that combine multiple patterns, geographic filters, or context‑based checks can increase query time; monitor Algolia’s search latency metrics to ensure the increase stays below ~10 ms for your typical load.
• Evaluation order: Rules are applied in creation order unless you assign a custom ranking field. Later rules can unintentionally override earlier boosts if they promote the same objectID to a different position or add conflicting filters.

Common mistakes and how to avoid them

• Missing anchoring: Leaving out this parameter causes the rule to match only exact queries, which often results in the rule never firing. Always specify anchoring (e.g., contains, is, startsWith).
• Invalid objectID in promote: If the objectID does not exist in the index, Algolia silently ignores the promotion. Verify the ID exists by fetching the object (/1/indexes/products/12345) before creating the rule.
• Overlapping rules: Two rules that both promote different records for the same condition can produce unexpected ordering. Use the Dashboard’s “Rule testing” tool with the exact query and context you plan to use in production, or assign explicit ranking values to control priority.
• Propagation delay: Rule changes are not instantly replicated across all Algolia servers. Allow a few seconds after creating or updating a rule before testing; otherwise you may see stale results during rollout.

Practical checklist

1. Define the keyword or pattern you want to match.
2. Choose the appropriate anchoring value.
3. Confirm the target objectID exists in the index.
4. Create the rule via the Admin API (or Dashboard) with a unique objectID.
5. Test with a search query that matches the condition and verify the promoted record’s position.
6. Monitor search latency after deployment to ensure the rule does not noticeably slow queries.