Save rule
This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.
This is documentation for v2 of the Ruby API clients, which is not the latest version. To see the documentation for the latest version, see Ruby v3.
This is documentation for v4 of the JavaScript API clients, which is not the latest version. To see the documentation for the latest version, see JavaScript v5.
This is documentation for v3 of the Python API clients, which is not the latest version. To see the documentation for the latest version, see Python v4.
This is documentation for v8 of the Swift API clients, which is not the latest version. To see the documentation for the latest version, see Swift v9.
This is documentation for v2 of the Kotlin API clients, which is not the latest version. To see the documentation for the latest version, see Kotlin v3.
This is documentation for v6 of the C# API clients, which is not the latest version. To see the documentation for the latest version, see C# v7.
This is documentation for v3 of the Java API clients, which is not the latest version. To see the documentation for the latest version, see Java v4.
This is documentation for v3 of the Go API clients, which is not the latest version. To see the documentation for the latest version, see Go v4.
This is documentation for v1 of the Scala API clients, which is not the latest version. To see the documentation for the latest version, see Scala v2.
Required API Key:
any key with the
editSettings
ACL
$index->saveRule(array Rule) $index->saveRule(array Rule, [ // All the following parameters are optional 'forwardToReplicas' => boolean ])
You’re currently reading the JavaScript API client v4 documentation. Check the migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.
You’re currently reading the Ruby API client v2 documentation. Check the migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.
About this method
Create or update a rule.
You can import and export rules from the Algolia dashboard, CLI or with an API client.
Examples
Read the Algolia CLI documentation for more information.
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
$rule = array(
'objectID' => 'a-rule-id',
'conditions' => array(array(
'pattern' => 'smartphone',
'anchoring' => 'contains',
)),
'consequence' => array(
'params' => array(
'filters' => 'category = 1',
)
)
);
// Optional, to turn the rule off
$rule['enabled'] = false;
// Optional, to add valid time ranges
$rule['validity'] = array(
array(
'from' => time(),
'until' => time() + 10*24*60*60,
)
);
$index->saveRule($rule);
Save a rule with alternatives enabled
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$rule = array(
'objectID' => 'a-rule-id',
'conditions' => array(array(
'pattern' => 'smartphone',
'anchoring' => 'contains',
'alternatives' => true
)),
'consequence' => array(
'params' => array(
'filters' => 'category = 1',
)
)
);
$index->saveRule($rule);
Save a rule with a context-based condition
1
2
3
4
5
6
7
8
9
10
11
12
13
$rule = array(
'objectID' => 'a-rule-id',
'conditions' => array(array(
'context' => 'mobile',
)),
'consequence' => array(
'params' => array(
'filters' => 'release_date >= 1568498400',
)
)
);
$index->saveRule($rule);
Parameters
objectID
|
type: string
Required
Unique identifier for the rule (format: 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 { objectID: objectID, conditions: conditions, consequence: consequence } |
forwardToReplicas
|
type: boolean
default: false
Optional
By default ( |
Rule ➔ rule
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:
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
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:
You can’t use the special characters This parameter goes hand in hand with the Otherwise, you can omit both. |
anchoring
|
type: string, enum
Optional
{ This parameter goes hand in hand with the Otherwise, you can omit both. |
alternatives
|
type: boolean
default: false
Optional
If For example, if For each word in Calculate the total number of alternatives by multiplying each word in
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: |
Rule ➔ rule ➔ consequence
params
|
type: params
Optional
Additional search parameters. Any valid search parameter is allowed.
Specific treatment is applied to these fields:
{ "query": query, "automaticFacetFilters": automaticFacetFilters, "automaticOptionalFacetFilters": automaticOptionalFacetFilters } |
promote
|
type: list
Optional
Objects to promote as hits. Each object must contain the following fields:
By default, you can promote up to 300 items per rule, and 100 items per promote group ( { "objectID": objectID, "objectIDs": objectIDs, "position": position } |
filterPromotes
|
type: boolean
default: false
Optional
Only use in combination with the { "promote": [ { "objectID": objectID, "position": position } ], "filterPromotes": true } |
hide
|
type: list
Optional
Objects to hide from hits. Each object must contain an 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 |
Rule ➔ rule ➔ consequence ➔ params
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, |
automaticOptionalFacetFilters
|
type: object
Optional
Same syntax as |
Rule ➔ rule ➔ consequence ➔ promote-params
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 |
Rule ➔ rule ➔ consequence ➔ hide
objectID
|
type: string
Required
Unique identifier of the object to hide. |
Rule ➔ rule ➔ validity ➔ timeRange
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
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 ( |
negative
|
type: boolean
default: false
Optional
Whether the match is inverted ( |
Rule ➔ rule ➔ consequence ➔ params ➔ query ➔ edits ➔ edit
type
|
type: string
Required
Type of edit. Must be one of:
|
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
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. |