Query rules

Query rules are an extension of the features available in the AI Search Engine. The rules provide IF - THEN logic that lets you influence the search results. This way you can manage the behavior of the search engine by telling it to promote specific products, replace the query or a word in the query or remove a word from it in specific circumstances.

The process of configuring query rules consists of three steps:

  1. Defining the condition that must be met. The condition pattern, which is the most important in the context of the whole query, is composed of a string of elements which are treated as a phrase.
  2. Defining the consequences. The search engine adapts its behavior according to the consequences associated with a condition.
  3. Defining the time when query rules apply.


AI Search engine must be implemented and configured.


Blank query rules settings
Blank Query Rules settings
  1. Go to Data Management icon Data Management > Search 2.0.
  2. Select an index from the list.
  3. Go to the Query rules section.
  4. On the right side of the screen, click Create new.
    Result: A new window opens.
  5. To adjust the query condidions, in the Conditions section, click Define.
    1. To define the method of checking the query, choose one of the four:
      • is - The phrase used by the customer must match exactly the whole phrase in the condition.
      • contains - The phrase used by the customer must match only a part of the phrase in the condition.
      • starts with - The phrase used by the customer must match the beginning of the phrase in the condition.
      • ends with - The phrase used by the customer must match the end of the phrase or word in the condition.
    2. Click Add phrase.
    3. Enter a phrase. You can do it in two ways:
      • In text field, type a word (or a phrase) in a singular form, with no typos.
      • Next to the text field, click the Facet icon in Query rules button. From the dropdown list select a facet (a product attribute) and its value (it can be a phrase). It is different from defining an exact query; you can define which attribute in general the query rule should look out for. For example, if you choose brand as the facet, the query rule will apply its consequence whenever any brand name is detected in the query.
    4. If you want to add more phrases, repeat the steps described in points b and c.
    5. Confirm the settings by clicking the Apply button.
  6. To define how search engine reacts to the defined conditions, in the Consequences section, click Define.
    1. Click Add Action.
    2. From the dropdown list, select an action.
      • Replace query - When a customer uses a specified phrase in the search query, you can replace it with another one. You can replace it with a query entered in the New query field that appears.
      • Replace word - When a customer uses a specific word in a query, you can replace it with another. You can replace a word with the one you entered in the New word field that appears.
      • Remove word - When a customer uses a specific word in a search query, you can remove it from the query. You can remove the word by entering it in the Word from query field that appears.
      • Promote item - When a customer uses a specific query, you can promote an item in the search results. You can promote an item by typing its name in the Item field and in the Position field defining its position in the search results.
      • Hide item - When a customer uses a specific query, you can hide some products from the search results. To hide the item, in the Item field, enter the name of the item.
      • Filter query results - Depending on the phrase used in a search query, you can filter the results according to the category, brand, size, color, and gender. You can only filter using Filterable or Facetable attributes. If you want to use an attribute to filter in query rules remember to add it to both. For more information about setting filterable and facetable attributes, see configuring AI Search article.
        To add filters, click the Add filter button that appers. Then from the dropdown list, select the filter.
    3. To add more consequences, click Add action and repeat the step described in point b.
    4. Confirm by clicking Apply.
  7. To define when the query rule applies, in the Schedule section, click Define.
    1. To launch query rules immediately, click Active immediately.
    2. To schedule the rules at specific time, click Scheduled.
      1. Enter the start date.
      2. Enter the end date.
      3. Select the time zone.
    3. Confirm by clicking Apply.
  8. To complete working on the query rule, you can either:
    • Save it as a draft by clicking Finish later.
    • To save and activate it, click Publish.

Conflicting consequences

When creating rules, it is possible that their settings might cause a conflict. A conflict emerges in a situation when two query rules should be activated by the same phrase and their consequences are mutually exclusive. The result managing system resolves such conflicts with precedence logic which criteria are explained in the Precedence logic section.

Precedence logic

Precedence logic is used to resolve potential conflicts with overlapping conditions for query rules, where the consequences are mutually exclusive. In order to indicate the precedence of the query rules, the system uses an algorithm. The precedence logic, ranked by importance, is as follows:

  1. Position: The earliest match wins (i.e. closest to the beginning of the query string).
  2. Match length: The longest match wins (in terms of the number of words from the query string).
  3. The way in which the condition matches the query, ordered from highest importance: Is > Starts with > Ends with > Contains.
  4. RuleID: If there are still conflicts after all other criteria have been applied, we take the smallest ruleID in lexicographical order. In practice it means, that one of the conficting rules which was created as the first wins. This final tie-breaker rule is guaranteed to break every tie and it will most likely only be used when there are duplicate rules. Essentially, rules are applied from the beginning of the query string to its end.


Promoting new item

When you introduce a new item in your offer, there isn’t much interaction with it at first, compared to items that were available earlier. By default, the item is at the end of the list of results. You can change this behavior and promote the item, which moves it towards the first positions in the list.

Let’s say you introduced a new Xbrand shoe model. You can set a rule: if query = Xbrand promote new Xbrand model to first position

Tip: In the AI Search Statistics, the average clicked position is available as a search statistic. You can promote an item to a specific position. If you see that position number three is the most clicked position, you can promote the item to that position.

When the brand appears in search, filter results only to that brand.

Another case where query rules come in handy is filtering your search results. For example, you can set a rule if query contains CoolBrand filter to brand = CoolBrand.

This way, all results will be narrowed down only to the CoolBrand products. If you want to apply such a filter for all brands, you can use facets in the following way: if query contains {brand} filter to {brand}.

This will always filter the results to the brand in the query, if a brand is detected in it.

Replace phone with smartphone


  • You offer items from brand XYZ in many categories (vacuum cleaners, lightbulbs, and so on).
  • You offer phones from other brands, but not XYZ.
  • You offer smartphones from brand XYZ.

If you want the query “XYZ phone” to search only for smartphones, you can set the following rule:

if query is "XYZ phone" OR "phone XYZ" replace "phone" with "smartphone"

Why synonyms (another possibility in search settings) are not a solution here?

Setting up a synonym would globally alter the way the search engine looks for items, it would treat “phone” and “smartphone” as equivalents. In this case we only want to manipulate the query if it contains a specific brand.

Hiding items

Sometimes you want to hide results that the search engine would consider relevant, however from a business perspective don’t make sense.
For example, when a user searches for alcohol-free beer, the search engine will try to match every word from the query with the items, so not only alcohol-free beers will appear in the result.
You can avoid this by creating a rule:: if query contains "alcohol free" hide results where 'alcohol' equals "true".

In order to do this, the items must have a custom attribute ‘alcohol’ with values “true” and “false” assigned accordingly.

Filtering by price range

You can also filter by range attributes. A good example is for filtering within a price range. If a customer is looking for cheap books, you can set a rule: if query is "cheap books" filter results to 'price' less than "10$".

Combining rules

Sometimes you will need more than one consequence to achieve your business case. You can add multiple consequences to one condition when setting up a rule. (Xbrand smartphone – change to ULT093model, filter to Xbrand, promote latest model)
For example let’s take a user’s query “Xbrand smartphone”. You might want to change the query to make it more relevant to your items, filter the results to Xbrand products and promote the newly released ULT093 model. You can set a rule: if query is "Xbrand smartphone" change query to "ULT093model" and filter to 'brand' equal to "Xbrand" and promote item "ULT093" to first position.


We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.



Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.