Rules

Overview

Rules engine allows you to create Query Configuration overrides based on user input, current date or other condition.

Examples of possible uses include:

  • Boosting specific brands in search results only on weekends;

  • Only apply brand boosting, if user query starts with water or mineral;

  • Use numeric boost for products by discount size only on the day of black Friday;

  • Show only the most popular products if user enters an empty query;

  • Automatically sort results from the cheapest to the most expensive, if user query includes word cheapest or inexpensive;

  • Include additional facets that allows filtering by screen size or resolution, if user query includes phrases like tv, monitor or television.

See examples at the bottom of the page on how to configure each of these rules.

Rules dashboard

Rules can be managed through the interactive interface directly from the dashboard.

To access rule configuration, click the following button in the Query List table:

Accessing rules from query list table

Or use "Manage rules" action directly from the query details/editing screen:

Accessing rules from query list details/edit page

Rule conditions

Rule conditions are used to describe the conditions when rule action should be applied. Each rule can have multiple conditions, which can be matched in two different ways (see Rule options section).

Rule search text condition

Rule search text condition allows checking user query text and apply rule based on what user is searching for.

For example, rule condition:

{
  "type": "searchText",
  "match": "contains",
  "input": "water"
}

Checks if user query contains the word water anywhere in the query. The condition inputs are case insensitive.

Search text condition supports the following text matching types. For example, for input bo, the following match types would yield these results:

  • startsWith - search phrases like book, books, box and boxes that starts with bo, would match the input, but queries inbox or cheap books would not;

  • endsWith - search phrases like placebo, or jumbo that ends with bo would match the input, but queries books or cheap books would not;

  • contains - Will match all of the phrases that match input anywhere in the query: book, books, expensive books, robots, bo;

  • isEqual - will only satisfy exact user query matches, like bo, BO or Bo;

  • isEmpty - only matches rule if user query text is empty. In this case, input field for search text condition is not required.

Is empty condition matching can be used to provide default product ranking when user search query is still empty. For example, you can use this rule to display the most popular products in the search box, while user still haven't entered any letters to the search input element.

Rule date condition

Date condition can be used to only apply rule action based on current day (weekday, exact day, date range).

Weekday

Weekday condition allows applying rule only on a specific weekday. For example, condition that only matches if current day is a Sunday:

{
  "type": "date",
  "match": "weekday",
  "weekday": 7
}

Exact day

Exact day condition allows applying rule only on a single specific day:

{
  "type": "date",
  "match": "exactDay",
  "date": "2022-09-01T00:00:00.000"
}

Days are matched against UTC timezone.

Date range

Date range condition is satisfied only if current date falls in a defined date range:

{
  "type": "date",
  "match": "dateRange",
  "dateFrom": "2022-12-24T00:00:00.000",
  "dateTo": "2022-12-31T00:00:00.000"
}

Both dateFrom and dateTo values are inclusive. Date ranges are matched against UTC timezone.

Rule term filter condition

This condition type allows to apply rule based on what term filters are being use in search query.

For example, the following rule condition:

{
  "type": "termFilter",
  "key": "category",
  "values": ["books", "fiction", "science-fiction"]
}

Would only apply rule if public search query contains category filter with any of the provided term filter values: books, fiction, science-fiction. Only filters of term type can be used as filter keys in this rule condition.

For matching with hierarchy filters, you can use the same schema with possible hierarchy filter values:

{
  "type": "termFilter",
  "key": "category",
  "values": ["books > fantasy", "books > fantasy > high-fantasy"]
}

Range filters are not supported yet.

Rule action

Rule action describes configuration overrides that will be made to the parent query, if rule conditions are satisfied. Rule action body, available fields and options are identical to one in Search Query Configuration.

{
  "action": {
    "facets": [
      {
        "type": "stats",
        "key": "price",
        "label": "Price"
      }
    ]
  }
}

Rule options

This section describes additional rule configuration options.

Condition match

Rule configuration conditionMatch field controls how rule conditions should match for the rule action to be applied:

  • any - rule will match if ANY of the defined rule conditions match;

  • all - rule will match if ALL of the defined rule conditions match;

{
  "conditionMatch": "all"
}

Rule behavior

Rule behavior specifies how rule action overrides are merged with the configuration of the parent search query.

Replace

If rule behavior is set to:

{
  "behavior": "replace"
}

Values of the fields, that are defined in rule action configuration, will override ones in query configuration.

For example, parent query configuration:

{
  "queryFields": {
    "name": 1
  },
  "match": "all",
  "selectFields": ["id", "name"]
}

merged with rule action (that has replace behavior):

{
  "queryFields": {
    "description": 5,
    "category": 2
  },
  "match": "any"
}

Would result in this final configuration:

{
  "queryFields": {
    "description": 5,
    "category": 2
  },
  "match": "any",
  "selectFields": ["id", "name"]
}

Merge

If rule behavior is set to:

{
  "behavior": "merge"
}

Values of the fields, that are defined in rule action configuration, will be merged with the ones in query configuration.

For example, parent query configuration:

{
  "queryFields": {
    "name": 1
  },
  "match": "all",
  "selectFields": ["id", "name"]
}

merged with rule action (that has merged behavior):

{
  "queryFields": {
    "description": 5,
    "category": 2
  },
  "match": "any",
  "selectFields": ["additional_field"]
}

Would result in this final configuration:

{
  "queryFields": {
    "name": 1,
    "description": 5,
    "category": 2
  },
  "match": "any",
  "selectFields": ["id", "name", "additional_field"]
}

Rule order

Main Rule object can optionally have an order, which controls the rule application order in the same query. If there are multiple rules that have their conditions satisfied, rules with lower order values will be applied first.

{
  "name": "User friendly rule description",
  "order": 20,
  "configuration": {}
}

For example, given parent search query configuration:

{
  "queryFields": {
    "name": 5
  },
  "match": "all",
  "selectFields": ["id", "name"]
}

and the following query rules:

[
  {
    "name": "Select fields merge",
    "order": 1,
    "configuration": {
      "action": {
        "queryFields": { "merged_query": 8 },
        "selectFields": ["merged_field"]
      },
      "behavior": "merge",
      "conditions": [
        {
          "type": "searchText",
          "match": "startsWith",
          "input": "book"
        }
      ],
      "conditionMatch": "any"
    }
  },
  {
    "name": "Select fields replace",
    "order": 2,
    "configuration": {
      "action": {
        "selectFields": ["replaced_field"]
      },
      "behavior": "replace",
      "conditions": [
        {
          "type": "searchText",
          "match": "startsWith",
          "input": "books"
        }
      ],
      "conditionMatch": "any"
    }
  }
]

The final configuration (if user is looking for books) is going to look like this:

{
  "queryFields": {
    "name": 5,
    "merged_query": 8
  },
  "match": "all",
  "selectFields": ["replaced_field"]
}

Rules API

It is possible to manage rules for your query from the API.

Create rule

API Reference: Create Rule

To create a new rule for the query, issue a POST request with selected query id and rule body:

POST /v1/indices/{indexId}/queries/{searchQueryId}/rules

{
  "name": "New rule",
  "order": 2,
  "configuration": {
    "action": {
      "selectFields": ["new_field"]
    },
    "behavior": "replace",
    "conditions": [
      {
        "type": "searchText",
        "match": "startsWith",
        "input": "books"
      }
    ],
    "conditionMatch": "any"
  }
}

The response, if rule creation is successful, will include newly created rule id:

{
  "id": "a5d54736-0f2d-4e5d-a362-3bc7bcfd46d2",
  "name": "New Rule",
  "createdAt": "2022-08-30T11:39:01.000Z",
  "createdBy": "c0f1252f-ca7d-ea8d-bc8a-4519cb7c14f8",
  "updatedAt": "2022-08-30T11:39:10.000Z",
  "order": 2,
  "configuration": {
    "action": {
      "selectFields": ["new_field"]
    },
    "behavior": "replace",
    "conditions": [
      {
        "type": "searchText",
        "match": "startsWith",
        "input": "books"
      }
    ],
    "conditionMatch": "any"
  }
}

Update rule

API Reference: Update Rule

To update existing rule, issue a PUT request with query and rule id:

PUT /v1/indices/{indexId}/queries/{searchQueryId}/rules/{ruleId}

The PUT request body has the same schema as the POST request.

List rules

API Reference: List Rules

To list all rules in the query use GET query:

GET /v1/indices/{indexId}/queries/{searchQueryId}/rules

Delete rule

API Reference: Delete Rule

To delete rule by its id, use DELETE query:

DELETE /v1/indices/{indexId}/queries/{searchQueryId}/rules/{ruleId}

Rule examples

Value boost on weekend

Add value boost for brand "Nike" but only on Saturdays and Sundays.

{
  "configuration": {
    "conditions": [
      { "type": "date", "match": "weekday", "weekday": 6 },
      { "type": "date", "match": "weekday", "weekday": 7 }
    ],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": { "boost": { "brand": { "Nike": 20 } } }
  }
}

Value boost by phrase

Boost specific tags if user search text query contains certain keywords.

{
  "configuration": {
    "conditions": [
      { "type": "searchText", "match": "contains", "input": "phone" },
      { "type": "searchText", "match": "contains", "input": "mobile" },
      { "type": "searchText", "match": "contains", "input": "iphone" },
      { "type": "searchText", "match": "contains", "input": "apple" }
    ],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": { "boost": { "tag": { "Mobile Phones": 15 } } }
  }
}

Numeric boost on specific day

Boost products with large discount on a specific day:

{
  "configuration": {
    "conditions": [
      {
        "type": "date",
        "match": "exactDay",
        "date": "2022-09-06T00:00:00.000Z"
      }
    ],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": { "boost": { "discount": 4 } }
  }
}

Smart sorting by keyword

Automatically sort products by from least expensive to most expensive, if query contains special keywords.

{
  "configuration": {
    "conditions": [
      { "type": "searchText", "match": "contains", "input": "cheap" },
      { "type": "searchText", "match": "contains", "input": "inexpensive" },
      { "type": "searchText", "match": "contains", "input": "affordable" }
    ],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": { "sort": [{ "price": "asc" }], "match": "any" }
  }
}

Sort by popularity if query text is empty

{
  "configuration": {
    "conditions": [{ "type": "searchText", "match": "isEmpty" }],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": { "sort": [{ "popularity": "desc" }] }
  }
}

Additional facets

Include additional facets that allows filtering by screen size or resolution, if user query includes phrases like tv, monitor or television.

{
  "configuration": {
    "conditions": [
      { "type": "searchText", "match": "contains", "input": "monitor" },
      { "type": "searchText", "match": "contains", "input": "tv" },
      { "type": "searchText", "match": "contains", "input": "television" }
    ],
    "conditionMatch": "any",
    "behavior": "merge",
    "action": {
      "facets": [
        {
          "key": "resolution",
          "label": "Screen Resolution",
          "type": "terms",
          "limit": 20
        },
        {
          "key": "screenSize",
          "label": "Screen Size (Inches)",
          "type": "range",
          "ranges": { "min": 0, "max": 50, "step": 10 }
        }
      ]
    }
  }
}