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.

Structure


The process of configuring rules consists of three steps:

  1. Defining the condition that must be met. The configuration of conditions allows to create three types of rules:
    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. Users 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 info 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 for all queries. For example, filter the results of every query to those that have the value of the online attribute set to true.

  2. Defining the consequences. The search engine adapts its behavior according to the consequences associated with a condition. Users can select from 9 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 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.
    • 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. 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.
  3. Defining the time when query rules apply.

Requirements


AI Search engine must be implemented and configured.

Procedure


Blank query rules settings
Blank Query Rules settings
  1. Go to AI Search icon 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 Create new.
    Result: A new window opens.
  5. 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 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 steps b and c.
    5. Optionally, in the Context (optional), you can enter the environment of the phrase where it was searched.
    6. In the Context tab, to define only the environment of the search (without query phrases), in the Define query context enter the context.
    7. Confirm the settings by clicking the Apply button.
  6. 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.
    5. 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 as explained in the Precedence logic section.

Precedence logic


Precedence logic is used to resolve conflicts with overlapping conditions for query rules, where the consequences are mutually exclusive.
In order to determine 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. 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.

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

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.

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

😉

Awesome!

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