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 reposition items in a user’s search results or activate filters based on query terms. Rules can also be enabled for a fixed period of time: this makes 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: a condition, a consequence, and a validity period. Of these three parts, only the consequence is required. The general behavior of a Rule is that if its condition is met, then its consequence applies.

Rules target specific indices, but can be automatically forwarded to replicas.


A Rule can have up to 25 conditions. Conditions contain a pattern string, an anchoring, and a context (none of which are required).

  • The pattern of a Rule’s condition is compared with a user’s query.
  • The context of a Rule is compared to their search’s ruleContexts.
  • Queries are compared to a condition’s pattern based on the condition’s anchoring: the anchoring determines what part of the query the pattern must match (for example, the beginning or the end).

Condition contexts are compared with your user’s search context and must match exactly.

A Rule without a condition applies to every search.

Because conditions are responsible for most of the use-case variation for Rules, this section describes different condition possibilities: query pattern, context, and conditionless.

Each condition for your Rule can contain both pattern string and contexts: in this case, both must match for the Rule to become active.


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

  • Promote a Result: Moves a specific object higher in the list of returned results.
  • Hide a Result: Removes a specific object from the list of returned 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 Matching Attributes: applies a filter to the returned 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.

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.


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?