Skip to content
Last update: January 30, 2024

Facets

Faceted search (sometimes also called faceted navigation) allows users to navigate through a web site by applying filters for categories, attributes, price ranges and so on. The main idea behind faceted search is to present the attributes of the documents of the previous search result as filters, which can be used by the user to narrow down search results along with calculate statistical counts to aid.

Facet calculation is requested by providing facet expression via the facet query parameter. Consider for example the following two facets:

facet: "color price:[TO 100),[100 TO 200])"

Sample return 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
"data": {
    "products": {
      "totalCount": 182,
      "items": [...],
      "range_facets": [
        {
          "name": "price_*-100_100-200",
          "ranges": [
            {
              "from": 0,
              "to": 100,
              "count": 5959,
              "includeTo": false,
              "includeFrom": true
            },
            {
              "from": 100,
              "to": 200,
              "count": 2143,
              "includeTo": true,
              "includeFrom": true
            }
          ]
        }
      ],
      "term_facets": [
        {
          "name": "color",
          "terms": [
            {
              "term": "EXPRESSO",
              "count": 2343
            },
            {
              "term": "Sierra Brown",
              "count": 362
            },
            ...
        }]
    }
}

TermFacet expression

To retrieve facet counts for all occurring values of a product document field the following notations can be applied:

Query Description
facet: "category.path" Counts the products of all categories.
facet: "{propertyName}" Counts the product documents for all occurring values of custom properties.
facet: "properties.{propertyName}" Counts the product documents for all occurring values of custom properties using the specified property name.

TermFacet result

The term type facets provide the counts for each of the different values the query parameter happens to have.

Field Description
name Represents the key of the requested facet taken from the facet expression.
terms.term Represents one of the values for the field specified in the facet expression,
for which at least one product could be found.
terms.count Represents the number of products for which the term applies.
terms.isSelected Indicates whether the requested facet term is used in the filter expression.
This flag simplifies displaying the already selected facet terms on the frontend.

RangeFacet expression

To aggregate facet counts across ranges of values, the range qualifier can be applied analogous to the filter parameters. The range notation is applicable to the date, time, datetime, number and money type fields.

Query Description
facet: "price.{currency}:[TO 100),[100 TO 200])" Counts the products whose price falls in one of the specified ranges.
facet: "properties.{propertyName}[1 TO 100)" Counts the products whose values of the custom property fall in one of the specified ranges.

RangeFacet result

The range facet type counts the products for which the query value is a range specified in the range expression. Range facets are typically used to determine the minimum and maximum value for example product prices to filter products by price with a range slider.

Field Description
name Represents the key of the requested facet taken from the facet expression.
It is built from range parameters concatenated by "_". Example: price_*-100_100-200.
ranges.from Represents the lower endpoint of the range in number format.
ranges.to Represents the upper endpoint of the range in string format.
ranges.count Represents the number of products that fall into the specified range.
ranges.includeTo Indicates whether the lower bound of the range is included.
ranges.includeFrom Indicates whether the upper bound of the range is included.
ranges.isSelected Indicates whether the requested facet term is used in the filter expression.
This flag simplifies displaying the already selected facet terms on the frontend.