API Reference / API Methods / Query rules / Save rule
Feb. 26, 2019
Required API Key: any key with the editSettings ACL
Method signature
$index->saveRule(array queryRule)

$index->saveRule(array queryRule, [
  // All the following parameters are optional
  'forwardToReplicas' => boolean
])

About this method

Create or update a single rule.

Examples

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',
    'condition' => array(
        'pattern'   => 'smartphone',
        'anchoring' => 'contains',
    ),
    'consequence' => array(
        'params' => array(
            'filters' => 'category = 1',
        )
    )
);

// Optionally, to disable the rule
$rule['enabled'] = false;

// Optionally, to add validity time ranges
$rule['validity'] = array(
  array(
    'from' => time(),
    'until' => time() + 10*24*60*60,
  )
);

$index->saveRule($rule);

Parameters

objectID
type: string
Required

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

Note that for some languages, the objectID is duplicated in the queryRule.

queryRule
type: rule
Required

The rule object, its condition(s) and consequence(s).

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

By default, this method applies only to the specified index. By making this true, the method will also send the rule to all replicas.

queryRule ➔ rule

objectID
type: string
Required

Must contain the same value as the objectID above.

condition
type: condition
Required

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

{
  "pattern": pattern,
  "anchoring": anchoring,
  "context": context
}
consequence
type: consequence
Required

Consequence of the rule. At least one of the following object 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 is not interpreted by the API.

enabled
type: boolean
default: true
Optional

Whether the rule is enabled. Disabled rules remain in the index, but are not 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 is ignored the rest of the time. The list must not be empty.

queryRule ➔ rule ➔ condition

pattern
type: string
Required

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}. 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.

An empty pattern is only allowed when the anchoring is set to is.

anchoring
type: string, enum
Required

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

context
type: 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).

queryRule ➔ rule ➔ consequence

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, position

{
  "objectID": objectID,
  "position": position
}
hide
type: list
Optional

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

{
  "objectID": objectID
}
userData
type: 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.

queryRule ➔ 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; 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
type: object
Optional

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

queryRule ➔ rule ➔ consequence ➔ promote-params

objectID
type: string
Required

Unique identifier of the object to promote.

position
type: integer
Required

Promoted rank for the object (zero-based).

queryRule ➔ rule ➔ consequence ➔ hide

objectID
type: string
Required

Unique identifier of the object to hide.

queryRule ➔ 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).

queryRule ➔ 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 (true) or conjunctive (false). If the filter applies multiple times, e.g. 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 instead.

queryRule ➔ rule ➔ consequence ➔ params ➔ query ➔ edits ➔ edit

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

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

1
2
3
4
{
  "updatedAt":"2013-01-18T15:33:13.556Z",
  "taskID": 678
}
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?