Rules matching algorithm

If your index has many rules, you need to be careful not to create conflicts, since rules may contradict or override each other.

To reduce conflicts, Algolia applies the following rules matching algorithm:

1. Sort all matching rules with a tie-breaking algorithm.
2. Compare the sorted rules to check for conflicts. If there is a conflict, exclude rules with the lowest precedence.
3. Apply the remaining rules to the query.

Rules precedence

Algolia uses a tie-breaking algorithm to determine the precedence of all rules that apply to a query. The next criterion is only considered if there’s a tie in the preceding criteria.

More specific rules typically have higher precedence.

The tie-breaking algorithm that determines rule precedence applies these criteria:

1. Position. The match closest to the beginning of the query string wins.

2. Match length. The longest match wins. The match length is determined by the number of words matched from the query string and the number of filters matched from the query parameters.

3. Anchoring. Rules with anchoring patterns are ranked in this order: is > starts with > ends with > contains.

4. Context. Rules with context have a higher priority than other rules.

5. Filters. Rules with filters have a higher priority than other rules.

6. Literals over placeholders. If a word matches a literal and a facet value, the literal takes precedence.

7. Temporary over permanent. If the temporary and permanent rules match, the temporary rule takes precedence.

8. Rule ID. If there are still conflicts after all other criteria have been applied, the rule with the smallest rule ID (objectID) wins, in lexicographical order wins.

This final criterion guarantees to break any remaining ties. It often only applies when there are duplicate rules.

Rules apply from the beginning of the query to its end.

The precedence algorithm also applies to rules with multiple conditions. Each condition is evaluated as if it were an independent rule.

For more information about rules applied to recommendations, see Recommend rules.

Conflicting conditions

After ranking rules by precedence, only conflicting rules with the highest precedence are retained. Conflicting rules with lower precedence are excluded.

Overlapping pattern conditions

Rules with the pattern condition might conflict with each other due to overlapping patterns.

Rules with overlapping patterns are excluded.

Consider the query Enchanted forest adventure, and an index with several rules. Each rule matches a different pattern. The rules are ranked by precedence and only rules A and B are retained. The pattern of rules B and C overlaps with rule A, which leads to their exclusion.

1 2 3 4 5 
`pattern` [enchanted] [forest] [adventure] Rule A [------------------] KEPT Rule B [------------------] EXCLUDED: overlaps with rule A Rule C [------] EXCLUDED: overlaps with rule A Rule D [---------] KEPT 

Multiple rules can still match the same query, provided they match a distinct set of words.

Rules with an empty query pattern don’t overlap with any other pattern. They will all be applied, as long as there isn’t any other conflict.

Intersecting filter conditions

For rules with intersecting filters conditions, the rule with the lowest precedence is excluded.

Conflicting consequences

Two rules might try to apply the same consequences, for example, pinning different records to the first position. Consider the following example:

• Rule 1: if a query contains “Shakespeare”, then promote the record “The Lost Shakespeare Diaries”, with objectID “1”, to the first result.
• Rule 2: if a query contains the phrase “how much is”, then promote the record “Full Price List”, with objectID “2”, to the first result.

What happens when the query is “how much is Shakespeare”?

The conditions of rules 1 and 2 are different. Yet the consequences overlap: both rules try to pin two different records to the first position. In this case, the consequences apply depending on the objectID of the promoted record. The record with the lowest objectID (in lexicographical order) wins. Subsequent promotions are shifted down by one position.

In the previous example, the record “The Lost Shakespeare Diaries” is promoted to the first result, since it has a smaller objectID. The record “Full Price List” is then pinned to the second position.

Edge cases

If a rule removes a word from the query string, all subsequent rules that would have been triggered by this word are ignored.

If a rule replaces the query string entirely, all subsequent rules are ignored.

Context-only rules

For rules that have only a context as a condition, the following applies:

• They have a higher priority than general rules and rules without conditions.
• They always trigger in this context and never conflict with other rules.

Rules without conditions

For rules that don’t have any conditions, the following applies:

• They have a higher priority than general rules.
• They always trigger and never conflict with other rules.

Effect of promotions on relevance

Only records from the same index can be promoted. Promoted records have to be explicitly identified by their objectID.

A promoted record is included in search results, even if it doesn’t match the query. If it matches the query, it’s removed from its original position and inserted at its promoted position, even if the original position was better than the promoted position. Promoted positions are restricted to a range of 0 to 300. Inside the same rule, each promoted record must have a unique promoted position.

If promoted records from two distinct rules are triggered for the same query, the following applies:

• Duplicates are merged, using the best position.
• If the resulting positions conflict between distinct records, records are shifted down until a free slot is found.
• All regular search results are shifted down to ensure that all promoted records are as close to their promoted position as possible.

Hidden records are removed from the search results. The following hits are shifted up so that pagination works seamlessly.

User data

You can use rules to inject custom data into the search results, such as banners. Since this data isn’t part of the index, it doesn’t interfere with things like pagination. User data can be any JSON object. It’s not interpreted by the API.