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.

Create a new business rule

  1. Navigate to Relevance > Query Rewriting.

    Relevance menu

  2. Under Business Rules, click View.

  3. Click the Add icon icon.

    The New Rule window appears:

    New Rule window

    General Condition Action

    In the General column, only the Name field is required. Other fields are optional:

    • Description is an arbitrary string you can use to describe this rule.

    • Rule Group can be a user-defined group that you use to organize your rules.

    • Tags are another way to organize your rules. Tags appear as facets in the Business Rules interface, so you can filter the set of visible rules by tag.

    • Priority can be used to determine which rule should apply first if two rules are activated for the same request. If two rules have the same priority, one will be chosen at random to be applied before the other. The value range is 1 to infinity.

    • Enabled means that this rule is applied (but not necessarily published). Disabling a rule helps ensure that it is not accidentally published.

    Conditions are triggers that activate the rule when they match the current date and time, query, or field values.

    See Rule conditions below.

    A rule can take different types of actions when the specified conditions are met.

    See Action types below. You can also create custom actions.

  4. Click Save.

Edit, enable, or disable an existing rule

  1. Navigate to Relevance > Query Rewriting.

  2. Under Business Rules, click View.

  3. Hover over the rule you want to edit.

  4. Click the Edit icon icon next to the rule.

Publishing your changes

How to publish updated business rules
  1. In the Business Rules screen, click the PUBLISH button.

    Fusion prompts you to confirm that you want to publish your changes.

  2. Click PUBLISH.

Tip
You can un-publish a query rewrite by changing its status to "pending" or "denied", then clicking PUBLISH.

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

  • Boost List

    Boost particular items to the top of the results.

    For example, boost gift items on sale to the top of search results during the first weeks of December.

    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.

  • Banner

    Display a user-defined banner message when the rule fires.

    For example, a search for "office dvd" could return a results page that includes a special banner that advertises "The Office DVD boxed set: Now 50% off".

  • Bury List

    When the condition is met, the rule down-ranks all the documents with the specified field values for the given field name. Use this action when you want to minimize certain results without blocking them.

  • Block List

    Suppress one or more items from the list of results.

  • Set Facets

  • Set Params

    This rule type corresponds to the Additional Query Parameters stage and permits the complex modeling of a rule.

  • Filter List

    Change the results so only a specified set of content is shown.

    For example, a search for "kids movies" could 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.

  • Redirect

    Send users to a different URL instead of the search results.

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

  • Boost Attributes

    This action boosts documents with specific attributes by adding the bq or boost parameter to the incoming Solr request and executing a boost query.

    When the condition is met, the boost query is executed and the docs returned from the boost query are boosted in the results. For example, this action can be used to boost items where color="red" when the incoming query contains "red".

  • My Custom Rule

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

Query Elevation Component for Rule Actions

Fusion AI currently supports the usage 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 component in the solrconfig.xml file:

    <arr name="last-components">
     <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.

Using the UI to create custom rules

How to create a custom rule using the UI
  1. Navigate to Relevance > Query Rewriting.

  2. Under Business Rules, click View.

  3. Click click the Add icon icon.

    The New Rule window appears.

  4. Enter the general parameters and conditions for this custom rule.

  5. Under Action, select My Custom Rule.

  6. Select the query pipeline to use when this rule is triggered.

  7. Enter a name for this custom rule type.

  8. Optionally, you can click Add under Return Parameter Policy Override to override the value of a parameter returned from the specified pipeline:

    1. Enter the name of the parameter.

    2. Enter the desired value.

    3. Select one of the following policies:

      • Replace the returned value with the specified value.

      • Append the specified value to the returned value.

      • Remove the specified parameter from the set of returned parameters.

      • Default

    4. Enter a value for From Custom Rule.

Using the API to create custom rules

You can create a custom rule type by POSTing to the /query-rewrite/schema endpoint. A custom rule type has:

  • an id field, which must be unique across all apps in Fusion (global namespace)

  • a pipeline_id that is invoked during rule processing

  • a display_type that gives a human-friendly name to the custom rule type

  • a JSON schema that defines a set of parameters to pass to the pipeline during rule processing

For example, the following custom rule type with ID some_custom_rule calls the custom_pipeline during rule processing and passes the values for custom_param1 and custom_param2:

curl -XPOST -H "Content-type:application/json" \
"http://localhost:8765/api/v1/apps/best-buy/query-rewrite/schema" -d '{
  "id":"some_custom_rule",
  "pipeline_id":"custom_pipeline",
  "response_pipeline_id":"do_more_custom_stuff_here",
  "display_type":"Custom Rule",
  "schema": {
    "type" : "object",
    "properties" : {
      "custom_param1" : {
        "type" : "string",
        "title" : "Custom Param One",
        "description" : "Some param from the rule creator"
      },
      "custom_param2" : {
        "type": "string",
        "title": "Custom Param 2",
        "description": "Some other param the rule creator needs to provide"
      }
    }
  }
}'

The rules editor UI will render this custom rule type with input fields for custom_param1 and custom_param2.

Here’s an example of how to create an instance of the custom rule type:

curl -XPOST -H "Content-type:application/json" \
http://localhost:8765/api/v1/apps/best-buy/query-rewrite/instances -d '{
  "id":"some_custom_rule1",
  "type":"some_custom_rule",
  "custom_type":"some_custom_rule",
  "name":"My Custom Rule 1",
  "description":"Call another pipeline to do custom things",
  "search_terms":["fusion"],
  "custom_param1":"This is the user-supplied value of custom_param1",
  "custom_param2":"This is the user-supplied value of custom_param2",
  "pipeline_id":"custom_pipeline",
  "display_type":"Custom Rule"
}'

When the user queries for "fusion", the custom rule will match (using search_terms) and the rules processing stage will call custom_pipeline, passing parameters custom_param1 and custom_param2 in the request.

Presumably, the custom_pipeline uses these parameters to perform some custom logic. When the invoked pipeline (such as custom_pipeline) returns, the rules processing stage running in the main pipeline extracts the parameters returned from the invoked pipeline and adds them to the main request. If the invoked pipeline has a rules processing stage, it will not re-invoke itself if any matching rules in the invoked pipeline would result in an infinite loop.

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.