Api reference icon

Query Rules REST API

Last updated 14 September 2017

Overview

This is the technical reference guide for our Query Rules REST API. Query Rules allows managing the set of rules for any given index. For a general overview, please see our Query Rules guide.

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

The Query Rules REST API follows the same conventions as our Search REST API. Please refer to the latter regarding request/response format, authentication and error handling.

Many of the rule endpoints manipulate rule objects, which are described in detail in the Rule Schema.

Quick Reference

Rules Management API

Path Verb Method

/1/indexes/{indexName}/rules/{objectID}

PUT Save a single rule

/1/indexes/{indexName}/rules/batch

POST Batch save multiple rules

/1/indexes/{indexName}/rules/{objectID}

DELETE Delete a single rule

/1/indexes/{indexName}/rules/clear

POST Clear all rules

/1/indexes/{indexName}/rules/{objectID}

GET Read a rule

/1/indexes/{indexName}/rules/search

POST Search for rules

Endpoints

Save a single rule

Path

/1/indexes/{indexName}/rules/{objectID}

HTTP Verb PUT

Description

Create or update the rule with the specified objectID.

Body

A rule object (see Rule Schema).

Response

  • taskID (integer): Unique identifier of the write task to save the rule. Can then be used with the standard task status mechanism.
  • updatedAt (string, ISO8601 date): Time stamp of the task’s creation.

Parameters

forwardToReplicas
type boolean
mandatory no
default false
description

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example

curl -X PUT \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}" \
    --data-binary @${rule_file}

Batch save multiple rules

Path

/1/indexes/{indexName}/rules/batch

HTTP Verb POST

Description

Create or update a batch of rules.

Each rule will be created or updated, depending on whether a rule with the same objectID already exists. You may also specify true for clearExistingRules, in which case the batch will atomically replace all the existing rules.

Body

An array of rule objects (see Rule Schema).

Response

  • taskID (integer): Unique identifier of the write task to save the rules. Can then be used with the standard task status mechanism.
  • updatedAt (string, ISO8601 date): Time stamp of the task’s creation.

Parameters

forwardToReplicas
type boolean
mandatory no
default false
description

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

clearExistingRules
type boolean
mandatory no
default false
description

When true, existing rules are cleared before adding this batch. When false, existing rules are kept.

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/batch" \
    --data-binary @${batch_file}

Delete a single rule

Path

/1/indexes/{indexName}/rules/{objectID}

HTTP Verb DELETE

Description

Delete the rule with the specified objectID.

Response

  • taskID (integer): Unique identifier of the write task to delete the rule. Can then be used with the standard task status mechanism.
  • updatedAt (string, ISO8601 date): Time stamp of the task’s creation.

Parameters

forwardToReplicas
type boolean
mandatory no
default false
description

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example

curl -X DELETE \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Clear all rules

Path

/1/indexes/{indexName}/rules/clear

HTTP Verb POST

Description

Delete all rules in the index.

Response

  • taskID (integer): Unique identifier of the write task to clear the rules. Can then be used with the standard task status mechanism.
  • updatedAt (string, ISO8601 date): Time stamp of the task’s creation.

Parameters

forwardToReplicas
type boolean
mandatory no
default false
description

When true, the change is forwarded to all replicas of this index. When false, replicas are not impacted.

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/clear"

Read a rule

Path

/1/indexes/{indexName}/rules/{objectID}

HTTP Verb GET

Description

Retrieve the rule with the specified objectID.

Response

A rule object (see Rule Schema).

Example

curl -X GET \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/${objectID}"

Search for rules

Path

/1/indexes/{indexName}/rules/search

HTTP Verb POST

Description

Search for rules.

Body

Search parameters, as a JSON object containing the following attributes (all are optional):

  • query (string): Full text query.
  • anchoring (string): When specified, restricts matches to rules with a specific anchoring type. When omitted, all anchoring types may match.
  • context (string): When specified, restricts matches to contextual rules with a specific context (exact match). When omitted, any generic or contextual rule (with any context) may match.
  • page (integer): Requested page (zero-based, default: 0).
  • hitsPerPage (integer): Maximum number of hits in a page (default: 20).

Response

  • hits (array of objects): Rule objects matched by the search query (see Rule Schema). Highlighting is provided through the standard mechanism (_highlightResult attribute inside every returned object).
  • nbHits (integer): Total number of rules matching the query.
  • page (integer): Returned page number (zero-based).
  • nbPages (integer): Total number of pages.

Example

curl -X POST \
     -H "X-Algolia-API-Key: ${API_KEY}" \
     -H "X-Algolia-Application-Id: ${APPLICATION_ID}" \
    "https://${APPLICATION_ID}.algolia.net/1/indexes/${indexName}/rules/search" \
    --data-binary '{"query": "something"}'

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.

© Algolia - Privacy Policy