View API Reference



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 saveRule saveRule saveRule saveRule save_rule save rule SaveRule save_rule
Batch save multiple rules

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

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

Get the object/definition of a specific rule.

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

Delete a specific rule using its id.

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

Delete all rules in an index.

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

Search for rules matching various criteria.

SearchRules searchRules searchRules searchRules searchRules search_rules search synonyms of SearchRules search_rules


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_-]+)
  • if (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).
  • then (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.
        • automaticOptionalFacetFilters (array of strings) [optional]: Same as automaticFacetFilters, but for optionalFacetFilters. The same syntax as query parameters can be used to specify a score: facetName<score=1>.
    • 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.