Guides / Managing results / Rules

Rules Overview

Search needs to be flexible. When you hold a promotion, you shouldn’t need to reconfigure search settings or modify individual records. If one of your products is not appearing where you want it to in your search results, you should be able to quickly 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 do not replace a good index configuration. 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 period of time, making Rules a great way of implementing sales or promotions.

Generally, Rules are used either for merchandising or fine-tuning your search and relevance.

To see some common applications for Rules, checkout our sections on merchandising with Rules and detecting user intent with Rules.

Structure of a Rule

Rules are composed of three parts: condition(s), consequence(s), and a validity period. Of these three parts, only the consequence is required. The general behavior of a Rule is that if one of a Rule’s conditions is met, then we apply its consequence(s). If a rule has no conditions, then we always apply its consequence(s).

Rules target specific indices, but can be easily copied to replicas.

Conditions

A Rule can have up to 25 conditions. If a rule has multiple conditions, it gets activated as soon as one of its conditions is met. In other words, conditions have an or relationship to one another. Conditions can contain a pattern string, an anchoring, and a context, though none are required.

To determine whether to trigger a rule, we follow these steps:

  • We compare the condition’s pattern string with a user’s query.
  • We base the comparision on the condition’s anchoring. Values for anchoring are is, contains, starts with, and ends with. The anchoring determines what part of the query the pattern must match: all of it, part of it, the beginning, or the end.
  • We compare a condition’s context to the search’s ruleContexts.

If a single condition includes both a pattern string and context, a search must contain both the matching pattern string and context for the condition to be met.

If a condition has a pattern string that is set to an empty string with the is anchoring, we apply the rule whenever the user has not yet entered a query.

If a condition has neither pattern, nor anchoring, nor context, it is a conditionless Rule and we apply it to every search.

These sections describes the different conditions parts further: query pattern, context, and conditionless.

Example conditions

Using a pattern with the is anchoring
1
2
3
4
{
  "pattern": "sale",
  "anchoring": "is",
}

We trigger a Rule with this condition whenever the query string is the word sale. If the query contains other words, we do not trigger the Rule.

Using a pattern with the contains anchoring
1
2
3
4
{
  "pattern": "featured",
  "anchoring": "contains",
}

We trigger a Rule with this condition whenever the query string contains the word featured.

Using context
1
2
3
{
  "context": "mobile"
}

We trigger a Rule with this condition whenever the search includes mobile in the ruleContexts.

Using pattern and context
1
2
3
4
5
{
  "pattern": "featured",
  "anchoring": "contains",
  "context": "mobile"
}

We trigger a Rule with this condition whenever the query string contains the word featured, and the search includes mobile in the ruleContexts.

Using an empty string pattern
1
2
3
4
{
  "pattern": "",
  "anchoring": "is",
}

We trigger the Rule with this condition whenever there is an empty search. We disable the rule as soon as a user starts typing.

Consequences

Though conditions are not required, Rules must have at least one consequence. Consequences modify the results returned by a search. There are many possible consequences:

  • Pin an Item: Moves a specific result higher in the list of results.
  • Hide an Item: Removes a specific result from the list of results.
  • Add a Query Parameter: Adds 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: Removes a specific word from your user’s search query (for search, not display purposes).
  • Replace Word: Replaces a word from your user’s search query with another word (for search, not display purposes).
  • Replace Query: Replaces the user’s entire search query with another query (for search, not display purposes).
  • Return Custom Data: Adds custom JSON data to the search response.
  • Filter/Boost Matching Attributes: Applies filters or optionalFilters 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. You can use this to automatically end promotions or sales on a specified end date.

Rules that respond to user queries

Rules can parse your users’ queries and apply a consequence if the query matches the Rule’s condition. Queries are matched 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.

If you would like to trigger a Rule on an empty query, or using context only, use the is anchoring, but set the text to be an empty string, or leave it blank in the dashboard.

Rules that respond to user context

If a Rule’s condition includes only a context, then that Rule’s consequence applies only 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 are using. A context can be any string value, but the search condition it specifies must be identifiable at search time. You must implement the logic to conditionally send contexts with your users’ queries. You can pass contexts through the ruleContexts search parameter.

Implementation

To implement a Rule with a context condition, you must:

  1. Create the Rule with the dashboard or the API.
  2. Conditionally assign its associated context to your user’s searches.

To clarify the process, let’s take an example. Suppose you own an electronics store. Using Analytics Tags, you’ve discovered that mobile users rarely find what they are looking for on the first page of search results. With some testing, you realize that this is because vague searches for accessories like “chargers” or “cases” return laptop chargers and cases first.

You want to add a Rule that promotes all items in your catalog that have the “phone” tag, but only if a user is searching from a mobile platform.

Concretely, this means that if mobile users search for cases, phone cases should be preferred over laptop cases. If they search for chargers, phone chargers should show up first.

Conditionless Rules

Rules without conditions apply to every search on the index. They’re an effective way of temporarily modifying your site’s search for a predefined period of time (e.g., for seasonal promotions).

Did you find this page helpful?