API client / Methods / Rules
Required API Key: any key with the editSettings ACL
Method signature
index.save_rule(dict Rule, {
    // All the following parameters are optional
    'forwardToReplicas': bool
})

About this method # A

Create or update a rule.

You can import and export rules from the Algolia dashboard, CLI or with an API client.

Examples # A

Save a rule#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
rule = {
    'objectID': 'a-rule-id',
    'conditions': [{
        'pattern': 'smartphone',
        'anchoring': 'contains'
    }],
    'consequence': {
        'params': {
            'filters': 'category = 1'
        }
    }
}

# Optional, to turn the rule off
rule['enabled'] = False

# Optional, to add valid time ranges
# Python 2 (with `time` and `datetime.timedelta` imports)
rule['validity'] = [
    {
        'from': int(time.time()),
        'until': int(time.time() + timedelta(days=10).total_seconds())
    }
]
# Python 3 (with `datetime.{datetime,timedelta}` imports)
rule['validity'] = [
    {
        'from': int((datetime.datetime.utcnow().timestamp())),
        'until': int(
            (datetime.datetime.utcnow() + timedelta(days=10)).timestamp())
    }
]

# Save the Rule.
response = index.save_rule(rule)

# Save the Rule, and forward it to all replicas of the index.
response = index.save_rule(rule, {
    'forwardToReplicas': True
})

Save a rule with alternatives enabled#

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
    'objectID': 'a-rule-id',
    'conditions': [{
        'pattern': 'smartphone',
        'anchoring': 'contains',
        'alternatives': True
    }],
    'consequence': {
        'params': {
            'filters': 'category = 1'
        }
    }
}
response = index.save_rule(rule)

Save a rule with a context-based condition#

1
2
3
4
5
6
7
8
9
10
11
12
13
rule = {
    'objectID': 'a-rule-id',
    'conditions': [{
        'context': 'mobile'
    }]s,
    'consequence': {
        'params': {
            'filters': 'release_date >= 1568498400'
        }
    }
}

response = movies.save_rule(rule)

Parameters # A

Parameter Description
objectID #
type: string
Required

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

For some languages, the objectID is duplicated in the Rule.

Rule #
type: rule
Required

The rule object, its conditions and consequences.

For a complete JSON rule object, see the saveRule definition.

{
  objectID: objectID,
  conditions: conditions,
  consequence: consequence
}
forwardToReplicas #
type: boolean
default: false
Optional

By default (false), this method applies only to the specified index. If true, the method also sends the rule to all replicas.

Rule ➔ rule #

Parameter Description
objectID #
type: string
Required

Must contain the same value as the preceding objectID.

condition #
type: condition
Optional

This parameter is deprecated in favor of conditions.

Condition of the rule, expressed using the following variables: pattern, anchoring, alternatives, context.

When the condition isn’t provided or is empty, the rule is active for all queries to the relevant index.

{
  "pattern": pattern,
  "anchoring": anchoring,
  "alternatives": alternatives,
  "context": context
}
conditions #
type: list of condition
Optional

A list of conditions that should apply to activate a rule. You can use up to 25 conditions per rule.

Filters can also be used as conditions.

[
  {
    "pattern": pattern,
    "anchoring": anchoring,
    "alternatives": alternatives,
    "context": context
  }
]
consequence #
type: consequence
Required

Consequence of the rule. At least one of the following objects must be used:

description #
type: string
Optional

This field is intended for rule management purposes, in particular, to ease searching for rules and presenting them to human readers. It’s not interpreted by the API.

enabled #
type: boolean
default: true
Optional

Whether the rule is enabled. Disabled rules remain in the index, but aren’t applied at query time.

validity #
type: list of timeRange
Optional

By default, rules are permanently valid. When validity periods are specified, the rule applies only during those periods; it’s ignored the rest of the time. The list must not be empty.

Rule ➔ rule ➔ condition #

Parameter Description
pattern #
type: string
Optional

Query pattern syntax

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

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

You can’t use the special characters *, {, }, :, and \ in the condition pattern.

This parameter goes hand in hand with the anchoring parameter. If you’re creating a rule that depends on a specific query, you must specify the pattern and anchoring. The empty "" pattern is only allowed when anchoring is set to is.

Otherwise, you can omit both.

anchoring #
type: string, enum
Optional

{ is | startsWith | endsWith | contains }: Whether the pattern parameter must match the beginning or the end of the query string, or both, or none.

This parameter goes hand in hand with the pattern parameter. If you’re creating a rule that depends on a specific query, you must specify the pattern and anchoring.

Otherwise, you can omit both.

alternatives #
type: boolean
default: false
Optional

If true, the pattern matches plurals, synonyms, and typos.

For example, if pattern is “shoe” and alternatives is true, the pattern matches “shoes”, as well as synonyms and typos of “shoe”.

For each word in pattern, Algolia can check up to 10 alternatives.

Calculate the total number of alternatives by multiplying each word in pattern by the number of alternatives per word. For example, the query to trigger a rule is “nice cat”:

  • “nice” has three alternatives: “fine”, “pleasant”, “amusing” (four total with “nice”) -“cat” has two alternatives: “kitten” and “kitty” (three total)
  • The total number of alternatives is 4x3 = 12.

If the total number of alternatives is more than 10, Algolia may not check some or even any of the words.

context #
type: string
Optional

Rule context (format: [A-Za-z0-9_-]+). When specified, the rule is only applied 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).

Rule ➔ rule ➔ consequence #

Parameter Description
params #
type: params
Optional

Additional search parameters. Any valid search parameter is allowed. Specific treatment is applied to these fields: query, automaticFacetFilters, automaticOptionalFacetFilters.

{
  "query": query,
  "automaticFacetFilters": automaticFacetFilters,
  "automaticOptionalFacetFilters": automaticOptionalFacetFilters
}
promote #
type: list
Optional

Objects to promote as hits. Each object must contain the following fields: objectID or objectIDs, position.

By default, you can promote up to 300 items per rule, and 100 items per promote group (objectIDs).

{
  "objectID": objectID,
  "objectIDs": objectIDs,
  "position": position
}
filterPromotes #
type: boolean
default: false
Optional

Only use in combination with the promote consequence. When true, promoted results will be restricted to match the filters of the current search. When false, the promoted results will show up regardless of the filters.

{
  "promote": [
    {
      "objectID": objectID,
      "position": position
    }
  ],
  "filterPromotes": true
}
hide #
type: list
Optional

Objects to hide from hits. Each object must contain an objectID field.

By default, you can hide up to 50 items per rule.

{
  "objectID": objectID
}
userData #
type: object
Optional

Custom JSON object that will be appended to the userData array in the response. This object isn’t interpreted by the API. It’s limited to 1kB of minified JSON.

Rule ➔ rule ➔ consequence ➔ params #

Parameter Description
query #
type: string or query
Optional

When providing a string, it replaces the entire query string. When providing an object, it describes incremental edits to be made to the query string (but you can’t do both).

{
  "edits": list of edit
}
automaticFacetFilters #
type: list of automaticFacetFilter
Optional

Names of facets to which automatic filtering must be applied. The paramater match the facet name of a facet value placeholder in the query pattern. For example, facetName1, facetName2. You can specify a score: facetName1\<score=5\>, facetName2\<score=1\>.

automaticOptionalFacetFilters #
type: object
Optional

Same syntax as automaticFacetFilters, but the engine treats the filters as optional. Behaves like optionalFilters.

Rule ➔ rule ➔ consequence ➔ promote-params #

Parameter Description
objectID #
type: string
true (unless using objectIDs)

Unique identifier of the object to promote.

objectIDs #
type: string[]
true (unless using objectID)

Array of unique identifiers of the objects to promote.

position #
type: integer
Required

The position to promote the objects to (zero-based). If you pass objectIDs, the objects are placed in this position as a group. For example, if you pass four objectIDs to position 0, the objects take the first four positions.

Rule ➔ rule ➔ consequence ➔ hide #

Parameter Description
objectID #
type: string
Required

Unique identifier of the object to hide.

Rule ➔ rule ➔ validity ➔ timeRange #

Parameter Description
from #
type: integer
Required

Lower bound of the time range (Unix timestamp).

until #
type: integer
Required

Upper bound of the time range (Unix timestamp).

Rule ➔ rule ➔ consequence ➔ params ➔ automaticFacetFilter #

Parameter Description
facet #
type: string
Required

Attribute to filter on. This must match a facet placeholder in the rule’s pattern.

score #
type: integer
default: 1
Optional

Score for the filter. Typically used for optional or disjunctive filters.

disjunctive #
type: boolean
default: false
Optional

Whether the filter is disjunctive (true) or conjunctive (false). If the filter applies multiple times, perhaps because the query string contains multiple values of the same facet, the multiple occurrences are combined with an AND operator by default (conjunctive mode). If the filter is specified as disjunctive, however, multiple occurrences are combined with an OR operator.

negative #
type: boolean
default: false
Optional

Whether the match is inverted (true) or not (false).

Rule ➔ rule ➔ consequence ➔ params ➔ query ➔ edits ➔ edit #

Parameter Description
type #
type: string
Required

Type of edit. Must be one of:

  • remove: when you want to delete some text and not replace it with anything
  • replace: when you want to delete some text and replace it with something else
delete #
type: string
Required

Text or patterns to remove from the query string.

[
  {
    "type": "remove",
    "delete": "red"
  }
]
insert #
type: string
Optional

Text that should be inserted in place of the removed text inside the query string.

[
  {
    "type": "replace",
    "delete": "red",
    "insert": "blue"
  }
]

Response # A

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format#

1
2
3
4
{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678
}
Field Description
updatedAt #
string

Date at which the indexing job has been created.

taskID #
integer

The taskID used with the waitTask method.

Did you find this page helpful?
Python v3