Business Rules

Business rules are manually-created formulas for rewriting queries. This is the most versatile strategy for creating custom query rewrites. It supports a variety of conditions and actions to address a wide range of use cases. When you need a very specific query rewrite, this is the best strategy.

Business rules are applied in the Apply Rules stage of the query pipeline.

Tip
When a query triggers a business rule, then the business rule overrides any query rewriting strategies that conflict with it.

Rule conditions

A rule can have one or more conditions which define the criteria that trigger the rule’s actions. The + Add Condition button allows you to add a condition type to a rule, and you can add multiple conditions to the same rule. When multiple conditions are defined, they are joined by Boolean OR, that is, one or more conditions must be met in order to trigger the rule.

Tips:
  • Since the Query condition can be configured with multiple criteria, you only need one condition of that type per rule.

  • To configure a rule that always fires with every query, select no conditions.

  • Multiple conditions of different types are joined by Boolean OR, that is, the rule is triggered when one or more conditions of different types are met.

  • By default, multiple field value conditions are joined by Boolean OR. To use AND so that all field value conditions must be met, go to the Apply Rules query pipeline stage and de-select Partially Matched Filter Queries Will Trigger the Rule.

Condition types are described below:

  • Dates

    The rule is applied only during the specified date and time range, which can be open-ended.

  • Query

    The rule is applied when the query terms match using one of the following methods:

    • Keywords

      The query term exactly matches one or more specified query terms. Keyword matching is case-insensitive. Multiple keywords can be specified with a comma delimiter.

      Tip
      This is the fastest type of query matching.
    • Text

      The query term is matched using text tokenization. For example, "customer" matches "customer service" and "customer help".

    Enter one or more query terms to match using the selected method. When you enter multiple terms, any match against one of them will trigger the action (logical OR).

  • Field Value

    This condition type identifies a predefined field name and value that may be present in the Solr filter query parameter (fq), such as an "on_sale" field whose value is "true". In that example, your rule could block results whose "on_sale" field value is "false".

    Field Value conditions require whole-field exact matches and are generally called programmatically, by a link to a category or a click on a facet.

Rule actions

A rule can have one or more actions that are triggered when the rule’s conditions are met by the incoming query.

Built-in rule actions

Rule type Description

Banner

Display a user-defined banner message when the rule fires. The Banner URL value included in the response is interpreted by the frontend, which displays the banner.

For example, a search for office dvd can trigger the rule to include a banner URL in the results response. The frontend interprets this value and returns a results page that includes a special banner that advertises "The Office DVD boxed set: Now 50% off".

Block List

Block a list of specific documents from appearing in the results.

Boost Attributes

Boost documents to a higher position within the results based on their attributes, such as color or manufacturer. When the condition is met, this action boosts documents with specific attributes by adding the bq or boost parameter to the incoming Solr request and executing a boost query.

For example, this action can be used to boost items where color="red" when the incoming query contains red.

Boost List

Boost a list of specific documents to a higher position within the results. For example, searches during the first weeks of December can return results with items on sale boosted to the top of the results.

To use the Query Elevation Component, you must first configure your Solr cluster using the instructions below, then select Use Query Elevation Component. Note that query elevation does not boost scores.

Bury List

Suppress a list of specific documents to a lower position within the results. Use this action when you want to minimize certain results without blocking them.

Filter List

Change the results so only a specified set of content is shown. For example, a search for kids movies can return only the titles whose MPAA_rating field matches G or PG.

To use the Query Elevation Component, you must first configure your Solr cluster using the instructions below, then select Use Query Elevation Component. Note that query elevation does not boost scores.

Ingroup Boost List

Boost a list of specific documents to a higher position within a group.

Ingroup Bury List

Suppress a list of specific documents to a lower position within a group.

Ingroup Pinned

Pin documents to a specific position within a group.

Pinned

Pin documents to a specific position within the search results.

Redirect

Send users to a different URL instead of the search results. The Redirect URL value included in the response is interpreted by the frontend, which performs the redirect.

For example, a search for black friday can redirect users to a special sale page instead of a list of products that match black and friday.

Response Value

Include a user-defined key-value pair as part of the results response, which is interpreted by the frontend per the needs of the search app.

For example, a Response Value rule can pass a key-value pair (e.g., specialTrigger: true) to a downstream metrics tracking system in order to test how often a candidate rule would file if enabled.

Another example use for a Response Value rule is to pass an ad code value that the frontend can ingest to display an ad that targets the specific query:

{
  "fusion" : {
    "ad-code" : [ "AD_CODE_99" ],
    "applicable_rules" : [ {
      "id" : "6NBtqjHu04",
      ...

You can also combine Reponse Value rules with all other rules, except banner and redirect rules:

Response Value and Boost List Rule Combo

Set Facets

Determine which facets are displayed to the user when a specific search query is made. For example, a search for tent can display facets for Outdoors and Recreation.

Set Params

Corresponds to the Additional Query Parameters stage and permits the complex modeling of a rule.

My Custom Rule

Select an alternate query pipeline that implements special processing for this rule. See below for more details.

FAQ

How do boost and pin rules differ?

Boost rules display affected documents higher in the search results than they would normally appear. In many cases, a boost rule makes the document the first result. However, this is dependent on the score of the document in relation to others.

Pin rules give more control over what position the document occupies in search results. For example, a pin rule can make the document occupy the 5th result position, ensuring the top 4 results are still displayed as expected.

How do bury and block rules differ?

Bury rules display affected documents lower in the search results than they would normally appear. Typically, these documents are found at the end of the search results. However, this is dependent on the score of the document in relation to others.

Block rules prevent affected documents from displaying at all. Unlike buried documents, which are usually found at the end of the search results, blocked documents do not appear.

How do ingroup rules differ from their counterparts?

When their rule conditions are met, boost list, bury list, and pinned rules apply to all documents within the returned search results.

Ingroup rules, however, apply to documents inside of specific groups only. For example, a search for shoes can return results grouped by their brand and model. Within the groups, there are different sizes and color variants. During Breast Cancer Awareness Month, an ingroup pinned rule can pin pink shoes, when available, to the top position within their group.

How do banner, redirect, and response value rules differ from other rules?

Banner, redirect, and response value rules return a value to the frontend as part of the results response without altering the results. However, a response value rule returns a generic, user-defined key-value pair instead of a specific value.

This behavior is unlike other rules, including boost or bury rules, which alter the results response.

Query Elevation Component for Rule Actions

Fusion AI currently supports the use of the Query Elevation Component (QEC) with boost lists and filter lists. You must configure Solr in order to enable the QEC option.

  1. Create an XML file named elevate.xml in the same directory as the solrconfig.xml file. Use the following as the contents of the file:

    <?xml version="1.0" encoding="UTF-8" ?>
    <elevate>
    </elevate>
    Note
    Although it will not be accessed for the elevation process, Fusion requires this independent elevate.xml file for the use of built-in rule actions with QEC.
  2. Add the following in the elevator searchComponent:

    <str name="config-file">elevate.xml</str>
  3. Add elevate as a 'last component' part of the select handler in the solrconfig.xml file. If a last-components array is not already defined, create it at the end of the select handler’s configuration. If one is already defined, add <str>elevator</str>.

      <arr name="last-components">
          <str>spellcheck</str>
          <str>elevator</str>
      </arr>
  4. When you create a new business rule, check the USE QUERY ELEVATION COMPONENT checkbox to use elevation.

    rules qec

Important
The Query Elevation Component only elevates documents within the query rewriting rules engine by the document id field. Ensure id is entered in the "FIELD NAME" option.

Custom rule actions

You can create custom actions for rules by creating a special query pipeline that implements the desired functionality, then creating a custom rule using the UI or the API.

Query pipeline stages for rules

These stages are part of the default query pipeline:

  • Apply Rules

    Rules query stages in the query pipeline This stage looks up rules that have been deployed to the _query_rewrite collection and matches them against the query. Matching rules that perform query rewriting are applied at this stage, while matching rules that perform response rewriting are applied by the Modify Response with Rules stage later in the pipeline.

  • Modify Response with Rules

    Most rules operate on the request, but some rule types, such as banner rules or redirect rules, do their work when the response comes back. The Modify Response with Rules stage applies those rules to the response. For example, a banner rule can add a banner URL to the response before returning it to the client.

Generally, if you are using rules then you need both of these stages enabled in your query pipeline. The Apply Rules stage must come before the Solr Query stage, while the Modify Response with Rules stage must come after the Solr Query stage. Disabling or removing the Apply Rules stage will disable rules entirely, while disabling or removing the Modify Response with Rules stage will disable only the rules that perform response rewriting, if any.

Rules on response signals

Response signals capture a list of rule IDs that match the query, in a multi-valued field named rule_ss. This allows for downstream analysis on rule activity using SQL, App Insights, or a custom Spark job.

Rules and experiments

The easiest way to integrate rules and experiments is to create one query pipeline with rules enabled and one without, with all other settings constant between the two pipelines. The pipeline without rules enabled must be configured manually.

To create an experimental rule, use tags on the rule and set the tag in one of the variant pipelines.