API Guide

Implementing Aggregate Filters

Aggregates scan over a result set to count values, bucket results and compute min, max and average of numeric values, then returning this data with the query response. For example, an aggregate on a category might return the count 20 for "tv", which means the search result contains 20 items that match the category "tv".

Buckets provide count values against custom groups of data. For example "buckets": "high:price >= 200,mid:price >=50 AND price < 200,low:price < 30" defines price conditions for high, mid and low price groups to aggregate on.

An aggregate filter is a pair, consisting of an aggregate and a filter. Aggregate filters change the result set to reflect the filters that are specified with them. An aggregate filter turns an aggregate into a filterable facet.

The following guide explains how facets work and how to implement them by integrating with the API.

Before you start:

Count and bucket aggregates need to be defined as steps in the query pipeline.

- id: count-aggregate
  params:
    fields:
      bind: countAggregate
- id: count-aggregate-filter
  params:
    fields:
      bind: count
    filters:
      bind: countFilters     
- id: bucket-aggregate-filter
  params:
    filter:
      bind: bucketFilter

Search query: "q":"t-shirt"

The following aggregates will be used in this example:

  1. Count size (assuming size is a String Array field)

  2. Count color (assuming color is a String field)

  3. Bucket price (assuming price is a Float field)

Description:

Everything is run using the global search query as the starting point, so in this example all counts include records which satisfy the global text query t-shirts. Note: the global text query can be empty, in which case all records are included.

Filtering by color

User selects the color blue, to only show blue t-shirts. Then:

We want the result set to include products with color = "blue" AND q = "t-shirt". We want aggregate 1 (size) to show size counts and aggregate 3 (price) to show price counts that have color = "blue" AND q = "t-shirt". We want aggregate 2 (color) to show counts that have q = "t-shirt" (as before).

{
    "variables": {
        "q": "t-shirt",
        "count": "size,color",
        "countFilters": ",color = 'blue'",
        "buckets": "high:price >= 200,mid:price >=50 AND price < 200,low:price < 30"
    }
}

In the above example, we are adding a filter for the color blue to the countFilters variable.

The number of filters in the countFilters must match the number of fields in the count variable. Notice how the countFilters value starts with a ,, indicated that the first value (for size) is empty.

The results now show all t-shirts that are available in the color blue. The facets show the same options for color, but the sizes and prices are now updated to only show sizes and prices that are available in blue, along with the corresponding count.

User selects the color blue and size M to only show blue t-shirts in size medium. Then:

We want the result set to include products with q = "t-shirt" AND color = "blue" AND size ~ ["M"]. We want aggregate 1 (size) to show size counts that have q = "t-shirt" AND color = "blue". We want aggregate 2 (color) to show counts that have q = "t-shirt" AND size ~ ["M"]. We want aggregate 3 (price) to show counts that have q = "t-shirt" AND color ~ "blue" AND size ~ ["M"].

Note, the size field is an array. Therefore the filter expression will check whether the size array ([]) contains (~) the size "M".

{
    "variables": {
        "q": "t-shirt",
        "count": "size,color",
        "countFilters": "size ~ ['M'],color = 'blue'",
        "buckets": "high:price >= 200,mid:price >=50 AND price < 200,low:price < 30"
    }
}

The results now show all t-shirts that are available in a blue color and size M. The facets show all colours available in size M, all sizes available in blue and all prices applicable to size M in blue, along with the corresponding count.

User selects the color blue, size M and price under $30 to only show blue t-shirts in size medium that are under $30. Then:

We want the result set to include products with q = "t-shirt" AND color = "blue" AND size ~ ["M"] AND price < 30. We want aggregate 1 (size) to show size counts that have q = "t-shirt" AND color = "blue" AND price < 30. We want aggregate 2 (color) to show counts that have q = "t-shirt" AND size ~ ["M"] AND price < 30. We want aggregate 3 (price) to show counts that have q = "t-shirt" AND color ~ "blue" AND size ~ ["M"].

{
    "variables": {
        "q": "t-shirt",
        ""
        "count": "size,color",
        "countFilters": "size ~ ['M'],color = 'blue'",
        "buckets": "high:price >= 200,mid:price >=50 AND price < 200,low:price < 30",
        "bucketFilter": "price < 30"
    }
}

In the above example, we are adding a filter for price < 30 to the bucketFilter variable.