Icon query rules white

Managing Query Rules

Last updated 14 September 2017

Managing Rules, Overview

Rules are managed much like Synonyms: they are edited independently of the index’s objects. Once they have been edited, they are automatically used by search queries.

Each index has its own, independent set of rules. When an index has replicas, however, rules can automatically be forwarded to all its replicas (using the forwardToReplicas parameter).

Editing rules

As all write operations in Algolia’s API, editing the rules is asynchronous.

All write methods return a task ID (via the taskID field in the response) that can be used to wait for the task to be published. Only when the corresponding task is published does the new version of the rules become available.

Rules may be edited one by one, using the saveRule and deleteRule methods. Or you may edit multiple rules at once via the saveRules method. The latter accepts a clearExistingRules parameter; when true, the new batch of rules entirely replaces the old rules, leading to an entirely atomic update. Alternatively, you can use the clearRules method to delete all rules from an index.

Retrieving rules

Rules can be retrieved one by one via the getRule method. This requires you to know the unique identifier of the rule you wish to retrieve.

When managing a large set of rules, you may find it more convenient to search them via the searchRules method. This allows you to search inside the rules’ patterns and descriptions, as well as filter by anchoring type or context.

Debugging rules

When you have a large set of rules, it may be difficult to understand which rules were applied on a given query, and why. Fortunately, Algolia provides a few tools to help you debug rule application.

The usual getRankingInfo parameter triggers additional information pertaining to the rules:

  • Promoted hits are labelled with a "promoted": true field inside the _rankingInfo object. This field is omitted from regular hits.
  • The list of applied rules is available inside the appliedRules top-level field. This field is omitted when no rule has been applied (even if enableRules is true).

In addition, the params response field contains search parameters after rule application, and as such reflects the side-effects of the rules.

Tip: When in doubt, you can always run the same query with enableRules=false and compare the results you get with and without rules.

© Algolia - Privacy Policy