Rules overview
On this page
- 1. What are rules used for?
- 2. Rule structure
- 3. Conditions
- 4. Consequences
- 5. Validity period
- 6. Rules responding to user queries
- 7. Rules responding to applied filters
- 8. Context-only rules
- 9. Conditionless rules
- 10. Context-only and conditionless rules deactivate consequences
- 11. Visual Editor or Manual Editor
Search needs to be flexible. Product promotions should be seamless: search setting adjustments or record updates aren’t needed. If one of your products isn’t appearing where you want it to in your search results, you should be able to reposition it.
Rules let you make precise and (if desired) temporary modifications to your search results.
Relevance and index settings provide the general structure for your search results. Rules let you optimize and dynamically adjust that structure.
Rules are no substitute for a well-configured index. Make sure you adjust your general relevance before adding rules.
What are rules used for?
Rules let you make precise, predetermined changes to your search results. For example, you can pin or hide items, boost or bury categories, or filter results based on the query. You can also enable rules for a fixed time, making rules a great way of implementing sales or promotions.
Rules are typically used either for merchandising or fine-tuning your search and relevance.
For more information about typical uses for rules, see Merchandising and Detecting intent.
The maximum number of rules per index depends on your Algolia plan.
Rule structure
Three elements define a rule: conditions, consequences, and a validity period. Of these three elements, only a consequence is mandatory. When a rule’s condition is satisfied, Algolia applies its consequences. If a rule has no conditions (a conditionless rule), Algolia always applies its consequences.
You can copy rules from the original target index to a replica or another index.
Conditions
A rule can have up to 25 conditions.
A rule with several conditions activates when any condition is satisfied.
In other words, conditions have an or
relationship to one another.
Conditions may contain a pattern string, anchoring, context, or filters.
To determine if a rule’s consequences apply:
-
Algolia compares the user’s query to the condition’s pattern. It bases the comparison on the condition’s anchoring. Values for anchoring are:
is
,contains
,starts with
, andends with
. The anchoring determines what part of the query the pattern must match: all of it, part of it, the beginning, or the end.- If you enable
alternatives
in the condition, user queries can match the condition’s pattern, even if the query is a plural, synonym, or typo of the pattern. Without alternatives, queries must precisely match the condition’s pattern and anchoring.
- If you enable
- It compares the condition’s filters to the filters applied to the search.
- It compares the condition’s context to the search’s
ruleContexts
.
If a single condition includes a pattern string, filters, and a context, a search must match all three for the condition to be satisfied. With three conditions, a rule activates if any is met.
If a condition has a pattern string that set to an empty string with is
anchoring, Algolia applies the rule if users haven’t yet entered a query.
If a condition has neither pattern, anchoring, context, or filters, it’s a conditionless rule, and Algolia applies it to every search.
Rules can respond to different types of conditions:
Example conditions
Using a pattern with is
anchoring
Trigger a rule with this condition whenever the query string is the word sale
and nothing else.
If the query contains other words, the rule isn’t triggered.
1
2
3
4
{
"pattern": "sale",
"anchoring": "is"
}
A pattern with contains
anchoring
Trigger a rule with this condition whenever the query string contains the word featured
.
The query can include other words.
1
2
3
4
{
"pattern": "featured",
"anchoring": "contains"
}
A context
Trigger a rule when the search includes mobile
in the ruleContexts
.
1
2
3
{
"context": "mobile"
}
Filters
Trigger a rule when the filter { "filters": "category:TV" }
applies to the query.
1
2
3
{
"filters": "category:TV"
}
The filters condition rejects an OR
combination of different attributes. For example, "filters": "brand:Guess OR color:orange"
returns an error.
Pattern, filters, and context
Trigger a rule when:
- The query contains the word
featured
filters
includescategory:TV
ruleContexts
includesmobile
.
1
2
3
4
5
6
{
"pattern": "featured",
"anchoring": "contains",
"filters": "category:TV",
"context": "mobile"
}
An empty string pattern
Trigger a rule when there is an empty search. The rule turns off as soon as a user starts typing.
1
2
3
4
{
"pattern": "",
"anchoring": "is"
}
Consequences
Though conditions aren’t required, rules must have at least one consequence. Consequences change the search results. Possible consequences are:
- Pin an Item. Insert an item at a specific position. If the item is already in the results, it moves to that position.
- Hide an Item. Remove a specific result from the list of results.
- Add a Query Parameter. Add a query parameter to your user’s search. For example, you could decrease the
aroundRadius
if your user’s query includes the words “near me”. - Remove Word. Remove a specific word from your user’s search query (for search, not display purposes).
- Replace Word. Replace a word from your user’s search query with another word (for search, not display purposes).
- Replace Query. Replace the entire user search query with another query (for search, not display purposes).
- Return Custom Data. Add custom JSON data to the search response.
- Filter/Boost Matching Attributes. Apply
filters
oroptionalFilters
matching the query to the results.
Validity period
If you want to apply a rule temporarily, you can set a validity period. The validity period determines how long a rule remains active. Use this to ensure promotions and sales end automatically.
Rules responding to user queries
Rules can parse user queries and apply consequences if the query matches the rule’s condition. Queries can match with conditions in the following ways:
- is: the entire query matches the condition string.
- contains: the entire query contains the condition string
- starts with: the query starts with the condition string.
- ends with: the query ends with the condition string.
To trigger a rule on an empty query use a context-only rule,
use is
anchoring but set the text to an empty string.
Rules responding to applied filters
If a rule’s condition includes filters, Algolia applies that rule’s consequences only if the filters in a search’s query parameters exactly match the condition’s filters.
For example, Algolia only triggers a rule with the condition {"filters": "category:TV"}
, only if the category
value is TV
.
Other filters like "category:Smartphone"
or "category:TV OR category:Smartphone"
don’t trigger the rule.
The primary goal of this condition is to create rules that trigger on specific category pages or when a user applies specific filters.
For example, you can define a rule with the condition {"filters": "category:TV"}
and a consequence to promote specific items.
The rule triggers when a user lands on the TV category page.
For more information, see Filters can trigger rules.
To use an attribute in a Rule condition with filters, you must first declare it in attributesForFaceting
.
Context-only rules
If a rule’s condition only includes a context,
the consequence only applies if the rule’s context exactly matches a value in the ruleContexts
parameter of a user’s search.
What are contexts?
Contexts provide information about your user’s search environment: for example, what section of a website they’re currently visiting or what device they’re using. A context can be any string value that doesn’t include whitespace characters. The search condition it specifies must be identifiable at search time.
You need to implement logic for sending contexts with queries.
You can pass contexts through the ruleContexts
search parameter.
Implementation
To create a rule with a context condition, you must:
- Create the rule (with the dashboard or the API).
- Conditionally assign its associated context to your user’s searches.
To clarify the process, consider the example of an electronics store. By looking at analytics tags, it’s clear that mobile users rarely find what they’re searching for on the first page of results. Testing indicates this is because vague searches for accessories like “chargers” or “cases” return laptop chargers and cases first. If mobile users search for cases, you can assume that they prefer phone cases over laptop cases. If they search for chargers, phone chargers should show up first.
To remedy this, add a rule that promotes all items with the “phone” tag but only for users searching from a mobile platform.
Conditionless rules
Rules without conditions apply to every search. They’re an effective way of temporarily modifying search for a predefined time, for example, for seasonal promotions.
You can create conditionless rules from the Algolia dashboard or with an API client.
Create a conditionless rule from the dashboard
- Select the Search product icon in the Algolia dashboard.
- Select the Rules section from the left sidebar menu in the dashboard.
- Under the heading Rules, select the index you’re adding a rule to.
- Select Create your first rule or New rule. In the drop-down menu, click Manual Editor. You can’t create conditionless rules with the Visual Editor.
- In the Condition(s) section, click the Remove button with the trash can icon at the top right of the condition.
- In the Consequence(s) section, set the relevant consequences.
- If this rule only applies for a certain period, select a time range in Additional Settings, under Timeframe in UTC.
- If you want to forward the rule to replicas or other indices, toggle Copy this rule to other indices and enter the relevant names.
- Save your changes.
Create a conditionless rule with an API client
To create a conditionless rule with an API client,
use the saveRule
method on a rule object but without a condition.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$rule = array(
'objectID' => 'a-rule-id',
'consequence' => array(
// Set relevant consequence(s)
)
);
// Set validity (optional)
$rule['validity'] = array(
array(
'from' => time(),
'until' => time() + 30*24*60*60,
)
);
$index->saveRule($rule);
Context-only and conditionless rules deactivate consequences
Since conditionless and context-only rules don’t have a query as a condition, these consequences are deactivated.
Consequence | Why is it deactivated? |
---|---|
Pin an item | The same item would always appear in the same position, usually at the top, for all queries and all users. Instead, consider adding a banner to promote items you want to pin. |
Remove Word, Replace Word, Replace Query. | Since there’s no query, there are no words to remove or replace. |
Filter/Boost Matching Attributes | Rules that filter and boost facets require users to type a facet attribute into the query. Since there’s no query or facet in the condition, there’s no filter for the rule to boost |
These limitations only apply to context-only and conditionless rules. Other rules can use the full range of consequences.
Visual Editor or Manual Editor
You can use the Visual Editor or Manual Editor to create rules.
- The Visual Editor has the most visual way of configuring rules but doesn’t offer all capabilities.
- The Manual Editor has more capabilities but is less visual.
Both editors use the Rules API.
Option | Capabilities |
---|---|
Visual Editor | • Promote and hide items • Boost, bury, and filter categories • Set priority on category ordering • Ban categories of items • Merchandise on filter selection • Merchandise based on date range for time-limited promotions • Merchandise based on geolocation, device, and user segment • Facet merchandising (facet type and value reordering) • Display banners • Configurable preview UI |
Manual Editor | • Merchandise on filter selection • Add custom data to rules • Display advanced banners |
Rules API | • Explore the Rules API • Build a custom merchandising UI |