View API Reference

Query Rules


API Method Description PHP Ruby JS Python iOS Android C# Java Go Scala name
Save a single rule

Create or update a single rule.

saveRule save_rule saveRule save_rule - - SaveRule saveRule SaveRule save rule
Batch save multiple rules

Create or update a specified set of rules, or all rules.

batchRules batch_rules batchRules batch_rules - - BatchRules batchRules BatchRules save rules
Read a rule

Get the object/definition of a specific rule.

getRule get_rule getRule read_rule - - GetRule getRule GetRule get rule
Delete a single rule

Delete a specific rule using its id.

deleteRule delete_rule deleteRule delete_rule - - DeleteRule deleteRule DeleteRule delete rule
Clear all rules

Delete all rules in an index.

clearRules clear_rules clearRules clear_rules - - ClearRules clearRules ClearRules clear rules of index
Search for rules

Search for rules matching various criteria.

searchRules search_rules searchRules search_rules - - SearchRules searchRules SearchRules search synonyms of
Export rules

Export all rules for a particular index using an iterator.

initRuleIterator export_rules exportRules iter_rules - - RulesIterator RulesIterable NewRuleIterator exportSynonyms


Query Rules allows performing some ad hoc pre- and post-processing on queries matching specific patterns. For more details, please refer to our Rules guide.


As their name implies, Query Rules apply at query time. Therefore, some search parameters control how rules are applied.

Most of the methods manipulate rule objects, described in detail in the Rule Schema below.

Just like for objects or synonyms, write methods for rules are asynchronous: they return a taskID that can be used by Wait for operations.

Rule Schema

A rule is described by a JSON object, containing the following fields:

  • objectID (string): Unique identifier for the rule (format: [A-Za-z0-9_-]+)

  • condition (object): Condition of the rule
    • pattern (string): Query pattern (see syntax below)
    • anchoring (string, enum) = { is | startsWith | endsWith | contains }: Whether the pattern must match the beginning or the end of the query string, or both, or none.
    • context (string) [optional]: Rule context (format: [A-Za-z0-9_-]+). When specified, the rule is contextual and applies only when the same context is specified at query time (using the ruleContexts parameter). When absent, the rule is generic and always applies (provided that its other conditions are met, of course).

  • consequence (object): Consequence of the rule. At least one of the following must be used:
    • params (object) [optional]: Additional search parameters. Any valid search parameter is allowed. Specific treatment is applied to these fields:
      • query (string or object) [optional]: When a string, it replaces the entire query string. When an object, describes incremental edits to be made to the query string. (Of course, replacing and editing is incompatible.) The following edits are supported:
        • remove (array of strings) [optional]: Tokens (literals or placeholders) from the query pattern that should be removed from the query string.
      • automaticFacetFilters (array of strings) [optional]: Names of facets to which automatic filtering must be applied; they must match the facet name of a facet value placeholder in the query pattern. Ex. facetName1, facetName2. You can specify a score: facetName1<score=5>, facetName2<score=1>.
      • automaticOptionalFacetFilters (array of strings) [optional]: Same syntax as automaticFacetFilters, but behaves like optionalFacetFilters.
    • promote (array of objects) [optional]: Objects to promote as hits. Each object must contain the following fields:
      • objectID (string): Unique identifier of the object to promote
      • position (integer): Promoted rank for the object (zero-based)
    • userData (object) [optional]: Custom JSON object that will be appended to the userData array in the response. This object is not interpreted by the API. It is limited to 1kB of minified JSON.
  • description (string) [optional]: This field is intended for rule management purposes, in particular to ease searching for rules and presenting them to human readers. It is not interpreted by the API.

Query pattern syntax

Query patterns are expressed as a string with a specific syntax. A pattern is a sequence of one or more tokens, which can be either:

  • Facet value placeholder: {facet:$facet_name}. Example: {facet:brand}.
  • Literal: the world itself. Example: Algolia.

Special characters ({, }, : and \) must be escaped by preceding them with a backslash (\) if they are to be treated as literals.