Create rules

About

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. Despite the many possibilities of altering the search performance, no code is required to set up the rules.

Structure

The process of configuring rules consists of three steps:

1. Defining the target audience of the rule.
2. Defining the conditions. The rule is only applied when all conditions are met.
   Click for video tutorial

   1. Rules that respond to customers’ queries - Rules can modify your customer’s queries and apply consequences if the query matches the condition of the rule. You can select among 4 query conditions:

      • is - The phrase in the condition and the search phrase entered by customer must be identical.
      • contains - The search phrase must include the phrase in the condition, but can also contain other phrases.
      • starts with - The search phrase must start with the phrase in the condition.
      • ends with - The search phrase must end with the phrase in the condition.

   2. Rules that respond to a context - If a condition of the rule has only a context defined, then the search results will be modified according to the defined consequences. It happens only if the context exactly matches a value in the context parameter of a customer’s search.

      More information about context

      • The context can be any string. For example, you can use it to differentiate searches made on a mobile device from those made on desktop.
      • Context is sent as a parameter with the search query.
      • Example of use: To make search results on mobile devices more accurate, you can promote results for smartphone chargers and cases instead of displaying chargers and cases for laptops on the top of search results.
      • To configure a context-based rule, you must:
        1. Assign context search parameter to customer searches.
        2. Create the rule in the application or through the API.

   3. Rules that apply only when the customer applies particular filters to the search (text filters or a range of numbers).

      Important: This condition can only be set if filterable or facetable search attributes are defined.
      More information about filter-dependent rules

      • Exact: the customer’s search filters must be exactly the same as this condition filter.
      • Contains Customer’s Filters: this condition filter must contain all the customer’s search filters (but can also contain other filters).
      • In Customer’s Filters: the customer’s search filter must contain all of this condition filter (but can also contain other filters)
      • Any: at least one of the customer’s search filters must match a value from this condition filter.

      Example:

      • The customer’s filters are color = green OR red OR white
      • The condition filter value is color = green, red.

      The result is:

      • Exact: does not match, the sets are different. The rule is not applied.
      • Contains Customer’s Filters: does not match, some customer filters are not included in the condition filters. The rule is not applied.
      • In Customer’s Filters: matches, green and "red" are included in green OR red OR white. The rule is applied.
      • Any: matches, there is at least one common element. The rule is applied.

   4. Rules that apply for all queries. For example, filter the results of every query to those that have the value of the online attribute set to true.

3. Defining the consequences. The search engine adapts its behavior according to the consequences associated with a condition. You can select from the following consequences:
   
   Click for video tutorial

   • Replace query - When a customer uses a specified phrase in the search query, you can replace the entire query with another one, 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 word, 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 enter the word to remove in the Word from query field that appears.

   • Promote item - When the query meets the condition, you can promote an item in the search results. You can promote the item by typing its name in the Item field. The Position lets you define the item’s position in the search results.

   • Hide item - When the query meets the condition, 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 search results by including or excluding (using the In or Not In operators) the item attributes such as category, brand, size, and so on.

     • Attribute values can be strings, numbers or dynamic values: expression results or aggregate results
     • You can use up to two dynamic values in a filter (for example, two aggregates or one aggregate and an expression).
     • If two or more rules match a given phrase and use dynamic values, up to two dynamic values from the winning rule are applied according to precedence logic.
     • The scope of attributes for filtering is defined in the Filterable and Facetable attributes section in the index settings. If you want to use an attribute to filter in query rules, remember to add it to both.
       Important: When setting up a filter in a Query Rule, 500 distinct attribute values are returned. If there are more distinct values for an attribute and the desired value does not appear in the dropdown menu, you can input the value manually.

   • Boost by attribute - When a customer uses a particular word or phrase in a search query, this consequence lets you:

     • boost the importance of an item attribute (such as brand), so the items with these attributes are more likely to occur in the search results.
     • demote the importance of an item attribute (such category), so the items with that attribute are less likely to occur in the search results.

   • Return no results - This consequence lets you return empty list when a customer uses a particular word or phrase in a search query.

   • Sort query results - When a customer uses a particular word or phrase in a search query, this consequence lets you sort the results in ascending or descending order.
     

     Important: If you select this consequence and the conditions are met, the order of the search results will not be personalized as they will be arranged either in descending or ascending order.

   • Return custom data - This is a possibility to return any custom data as a query rule consequence. The custom data is in JSON format and is located in the extras part of the search response object. You can also input a URL instead of a JSON. Example: If a query contains forbidden word, display customData equal to:
     

         {
             "custom404": "custom404.com",
             "forbidden-word": "forbidden word used"
         }

   • Sorting as a consequence - You can sort the results by a specified attribute in an ascending or descending order.
     Example: If a query contains all, sort the results by a title in the descending order.

   • Return no data - For a business case where you don’t want to display any search data. When returnNoData is set to true in a query rule, the search results will be empty.

4. Defining the time when query rules apply.

Requirements

AI Search engine must be implemented and configured.

Creating rules

1. Go to AI Search > Indexes.

2. Select an index from the list.

3. Go to the Rules section.

4. On the right side of the screen, click Add new.
   Result: A new window opens.

5. To define the profiles for whom you want to apply the rule, in the Audience section, click Define.

   1. Select one of the following options:
      • Everyone - The rule will apply to all profiles in your database.
      • Segments - The rule will apply to profiles in the selected segmentations.
        
        Important: You can use up to 10 various segmentations in all query rules in one index. When you use the same segmentation in several rules, it counts as 1 towards this limit.
   2. Follow the instructions depending on the option you selected:
      
      EveryoneSegments

      No further configuration in this section is needed. Confirm your choice by clicking Apply.

      1. Click Add segments.
      2. On the pop-up, select one or more segmentations.
      3. On the pop-up, confirm your choice by clicking Apply.
      4. Confirm the settings of the Audience section by clicking Apply.

6. To adjust the query conditions, in the Conditions section, click Define.

   1. In the Query tab, to define the method of checking the query, choose one 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.
      • Next to the text field, click the 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 steps b and c.
   5. In the Context tab, to define only the environment of the search (without query phrases), in the Define query context enter the context.
   6. In the Filters tab, define the filters that must be used by the customer in order for the rule to activate:
      1. Click Add filter.
      2. From the Attribute drop-down list, select the attribute.
      3. From the Filter match drop-down list, select the matching logic.
      4. Select the values that must match the logic:
         1. If the attribute is text-type, select the value or values from the dropdown list.
         2. If the attribute is a number, enter a value or range.
      5. To add more filters, click Add filter again.
         If you add multiple filters, they must all be met.
   7. Confirm the settings by clicking the Apply button.

7. To define how the search engine reacts to the defined conditions, in the Consequences section, click Define.

   1. Click Add consequence.
   2. From the dropdown list, select a consequence.
   3. Fill in the settings of the selected consequence.
   4. To add more consequences, click Add consequence and repeat steps b and c.
      If you add multiple consequences, they are all applied. For example:
      • if the first consequence is “promote item A” and the other is “replace word”, the result is “promote item A AND replace word”.
      • if one of the consequences is “Show no results”, the search will show no results regardless of any other consequences added before or after “Show no results”.
   5. Confirm by clicking Apply.

8. 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.

9. 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.

Multiple query rules

Query rule conflicts

When creating multiple 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 according to the following rules, in order of importance:

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 > Has.
4. Rule ID: If there are still conflicts after all other criteria have been applied, the system takes the smallest ruleID in lexicographical order. In practice, this means the rule that was created first wins. This final tie-breaker rule is guaranteed to break every tie and usually occurs only when rules are duplicated.

Essentially, rules are applied from the beginning of the query string to its end.

Matching filters in multiple query rules

If two (or more) Query Rules match a given phrase, the filters in their consequences are combined with the OR logic operator.

Example:

Query Rule 1: If phrase is Shoe, filter query results to category = “Men > Shoes”

Query Rule 2: If phrase is Shoe, filter query results to category = “Women > Shoes”

The search results will contain items that are either in the women shoes category or in the men shoes category. (Putting both consequences in one rule would filter the query results to items that belong to both categories at the same time).

Examples

Promoting a 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.

For example, if you introduced a new Xbrand shoe model, you can set the following rule: if query = Xbrand promote new Xbrand model to first 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

Assumptions:

• 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 items that the search engine would consider relevant, however from a business perspective don’t make sense.

For example, you have an item in your feed whose title is red t-shirt with white sneaker and we would like to hide this item from the search results because for some search queries it would match the query but from a business perspective it doesn’t make sense to show the item.

In such case, we can create a rule which hides the item with this title from search results: if query equals "sneaker" or "sneakers", hide item which "title" is "red t-shirt with white sneaker".

Filtering results by price range

You can also filter the results 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 consequences

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 customer 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.