Faceting and filtering - Bloomreach Experience - Headless Digital Experience Platform

Faceting and filtering

Simple filtering with fq

The fq parameter is an optional parameter that you can add to an API request to filter the results.

Facets

The fq parameter filters on facets. Your product feed must include any filtering elements that you want applied to your search results. Confirm with your Bloomreach representative that the element is enabled for filtering and properly mapped in Bloomreach's configuration.

Here’s an example request with the fq parameter appended to filter the results according to a particular color:

Example request

GET http:
account_id=<Bloomreach Provided Account ID>
&domain_key=example_com
&request_id=8438674518839
&url=http:
&request_type=search
&search_type=keyword
&q=dresses
&rows=10
&start=0
&fl=pid,title,brand,sku_swatch_images
&fq=color:"red"

fq parameter

The fq parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your product feed.

Attributes must be enabled and mapped by Bloomreach

Let your Bloomreach representative know which attributes in your product feed that you want to apply as filters to search results.

The  fq  parameter filters results to include only relevant items. For example, a major sports league has a website store that sells products to fans for every team in the league. The league has 32 teams, and each team has its own hats, t-shirts, jerseys,  tchotchkes, cups, and many other items. Showing all of these items to a customer is overwhelming, causing customers difficulty when they try to find exactly what they're looking for. You can use the fq parameter in your API calls to suggest to customers only items from their own teams.

Search using a single filter with multiple values

You can use the fq parameter as a single filter with multiple values. The following snippet uses fq to search for all dresses that are red, purple, or both colors:

&q=dresses
&fq=color:"red" OR "purple"

Search using multiple filters

You can add multiple fq parameters to search using multiple filters. The following snippet uses two fq parameters to search for red dresses made by Rebel in Rose:

&q=dresses
&fq=color:"red"
&fq=brand:"Rebel in Rose"

Search by category

You can add an fq parameter to constrain the search to a particular category:

&q=dresses
&fq=category:"1001"

Search with filters and categories

Your customers might be interested in filtering not only for color, but also for a particular size and within a certain category. To apply multiple filters, just add multiple fq parameters. The following snippet searches for red or purple dresses within category ID 1001, size 10:

&q=dresses
&fq=category:"1001"
&fq=color: "red" OR "purple"
&fq=size: "10"

Here, we’re looking for red or purple dresses within a category. The example’s category ID is 1001; your value is likely different. The results for this example include only products available in size 10, that are either red or purple, and are within category 1001. If there are dresses that don't fit all of these constraints, then they are omitted from the results.

Ranged facets

Your API responses can include ranged facets, some of which are defined in your request. Use the facet.range parameter:

&facet.range=price

Here's the corresponding response snippet, which shows you the number of items per price range:

Response snippet for facet.range

"facet_ranges": { 
            "price": [ 
                { 
                    "count": 9, 
                    "start": "*", 
                    "end": 100 
                }, 
                { 
                    "count": 0, 
                    "start": 100, 
                    "end": 200 
                }, 
                { 
                    "count": 0, 
                    "start": 200, 
                    "end": 300 
                }, 
                { 
                    "count": 0, 
                    "start": 300, 
                    "end": 400 
                }, 
                { 
                    "count": 0, 
                    "start": 400, 
                    "end": "*" 
                } 
            ] 
        } 

You need to parse the values that are in the facets_counts section of the response. The facet_queries section has custom range facets for numeric fields that you define in your request. The facet_fields section gives you facets that you can display to your site's users, such as brands and colors.

In the example response snippet, the price facet shows you that there are nine products priced $0 - $100, and zero products priced in the other ranges.

facet.range parameter

The facet.range parameter specifies the facets that need to be returned as ranges, typically on price or sale_price. To request counts for a set of ranges, append the facet.range parameter to your call:

&facet.range=sale_price

The specified facets will be returned with a default set of ranges:

  • [* TO 100]
  • [100 TO 200]
  • [200 TO 300]
  • [300 TO 400]
  • [400 TO *]

During integration, your Bloomreach TPM can change these defaults for you. You can also change your default ranges with the Facet Management tool in the Bloomreach Dashboard (instructions are provided here).

Any ranges configured in the Facet Management tool will be returned in the API response; you do not need to pass the facet.range parameters for those facets.

What's the difference between facet.range and fq?

Use facet.range to count the number of products falling within each range. Use fq to filter on facets.

For example, facet.range=sale_price gives you the number of products in your feed whose sale price fits within each sale price range. If you include fq=sale_price:[100 TO 200] in your request, then those only products with sale price between 100 and 200 are displayed. You can use facet.range to first determine whether there are any products available in each range, then allow the user to filter (fq) by ranges and see the results.

Sample response for facet.range with default ranges

"facet_ranges": { 
            "price": [ 
                { 
                    "count": 9, 
                    "start": "*", 
                    "end": 100 
                }, 
                { 
                    "count": 0, 
                    "start": 100, 
                    "end": 200 
                }, 
                { 
                    "count": 0, 
                    "start": 200, 
                    "end": 300 
                }, 
                { 
                    "count": 0, 
                    "start": 300, 
                    "end": 400 
                }, 
                { 
                    "count": 0, 
                    "start": 400, 
                    "end": "*" 
                } 
            ] 
        } 

Complex boolean filtering with efq

While the fq and facet.range filters apply filtering on facets, you can apply more complex filtering with the efq parameter.

efq parameter

The efq parameter applies a complex boolean filter to search results to include or exclude items that fit your parameter values. Any product attribute in your product feed is valid, such as brand names and sizes. Typically, the efq parameter is used for custom attributes that you include in your product feed to support additional business logic that you might need to filter.

efq or fq?

Values for the efq parameter are similar to values for the fq parameter. The difference between efq and fq is that efq supports complex boolean searches and fq filters on facets. You can use the fq parameter with the efq parameter to apply more complex filtering.

APIs supported

The efq parameter is supported in the Product Search and Content Search APIs.

efq operators 

OR operator

The OR operator expands results to include all items that belong to any specified set. For example, &efq=Fabric:("Cotton" OR "Linen") returns a set of all cotton items and all linen items.

Order does not matter for the OR operator. &efq=Fabric:("Cotton" OR "Linen") and &efq=Fabric:("Linen" OR "Cotton") behave the same.

Use Cases:

Suppose we have four products with the following attributes:

  Fabric Color
Product 1 Cotton, Linen Red
Product 2 Cotton Green
Product 3 Cashmere, Silk Blue
Product 4 Cotton, Acrylic Red

Using OR on a single attribute

&efq=Fabric:("Cotton" OR "Linen")

This returns a set of all cotton items and all linen items.

Returned Not returned

Product 1 (Cotton, Linen)

Product 2 (Cotton)

Product 4 (Cotton)

Product 3

Using OR on multiple attributes

&efq=Fabric:("Cotton") OR Color:("Red")

This returns a set of all cotton items and all red color items.

Returned Not returned

Product 1 (Cotton, Linen, Red)

Product 2 (Cotton)

Product 4 (Cotton, Red)

Product 3

AND operator

The AND operator limits results to include only items that belong to all specified sets. For example, &efq=Fabric:("Cotton" AND "Linen") returns a set of all items that are both cotton and linen.

Order does not matter for the AND operator. &efq=Fabric:("Cotton" AND "Linen") and &efq=Fabric:("Linen" AND "Cotton") behave the same.

Use Cases:

Suppose we have four products with the following attributes:

  Fabric Color
Product 1 Cotton, Linen Red
Product 2 Cotton Green
Product 3 Cashmere, Silk Blue
Product 4 Cotton, Acrylic Red

Using AND on a single attribute

&efq=Fabric:("Cotton" AND "Linen")

This returns a set of all items that are both cotton and linen. 

Returned Not returned

Product 1 (both Cotton and Linen)

Product 2

Product 3

Product 4

Using AND on multiple attributes

&efq=Fabric:("Cotton") AND Color:("Red")

This returns a set of all items that are both cotton and red.

Returned Not returned

Product 1

Product 4

Product 2

Product 3

NOT operator

The NOT operator (specified with "-", such as "-Fabric") expands or limits results to include all items that belong to specified sets, except those that also belong to other specified sets. For example, &fq=Fabric:"Cotton" and &efq=-Fabric:("Linen") returns a set of all cotton items that are not also linen.

Tip 
Use the - operator before the attribute name, not the attribute value.

  • Correct: -fabric:"linen"
  • Incorrect: fabric:-"linen"

Use Cases:

Suppose we have four products with the following attributes:

  Fabric Color
Product 1 Cotton, Linen Red
Product 2 Cotton Green
Product 3 Cashmere, Silk Blue
Product 4 Cotton, Acrylic Red
&fq=Fabric:"Cotton"
&efq=-Fabric:("Linen")

This returns a set of all cotton items that are not also linen.

Returned Not returned

Product 2

Product 4

Product 1

Product 3

How does applying efq on a facet value affect the facet response?

Applying efq on a facet value will only return the applied facet value and not return other values for that facet. For example, suppose you have a styles facet:

facet_fields: {
  styles: [
    {
      count: 81,
      name: "Tea dress"
    },
    {
      count: 74,
      name: "Waisted dress"
    },
    {
      count: 84,
      name: "Shift dress"
    },
    {
      count: 39,
      name: "Tiered dress"
    },
    {
      count: 29,
      name: "Swing dress"
    },
  ]
}

We will apply this efq to the facet response:

&efq = styles:("Tea dress")

The styles facet changes to:

facet_fields: {
  styles: [
    {
      count: 81,
      name: "Tea dress"
    },
  ]
}

SKU attribute level efq

efq can also be applied at the SKU level.

Suppose we have four SKUs with the following attributes:

    Material Sku_color
Product 1 SKU 1 Cotton Red
SKU 2 Cotton, Linen Pink
Product 2 SKU 3 Silk Red
SKU 4 Linen Green

OR operator with SKUs

&efq=Material:("cotton") OR Sku_color:(“red”)

This returns a set of all SKUs that are available in cotton or red.

Returned Not returned

Product 1: SKU 1 and 2

Product 2: SKU 3

Product 2: SKU 4

&efq=Material:(“cotton” OR “linen”)

This returns a set of all SKUs that are available in cotton or linen.

Returned Not returned

Product 1: SKU 1 and 2

Product 2: SKU 4

Product 2: SKU 3

AND operator with SKUs

&efq=Material:("cotton") AND Sku_color:(“red”)

This returns a set of all SKUs that are available in both cotton and red.

Returned Not returned

Product 1: SKU 1

Product 1: SKU 2

Product 2: SKU 3 and 4

&efq=Material:(“cotton” AND “linen”)

This returns a set of all SKUs that are available in both cotton and linen.

Returned Not returned

Product 1: SKU 2

Product 1: SKU 1

Product 2: SKU 3 and 4

NOT operator with SKUs

&efq:-Material(“cotton”)

This returns a set of all SKUs that are not available in cotton.

Returned Not returned

Product 2: SKU 3 and 4

Product 1: SKU 1 and 2

efq with Product and SKU-level attributes

Within a single efq parameter, OR and AND can only accept all product-level attributes or all SKU-level attributes. That is, you cannot combine product-level attributes with SKU-level attributes in a single efq parameter. For example, suppose brand and gender are product-level attributes and color and size are SKU-level attributes:

&efq=brand:("...") OR gender:(“...”) //valid
&efq=brand:("...") OR size:(“...”) //not valid, will return a 400 error response
{
    "status_code": 400,
    "message": "[u'Malformed efq param: -(sku_size:(\"11-12 years\" OR \"10-11 years\")) OR price:\"39\"']"
}

If you want to apply efq on both product-level and SKU-level attributes, then send separate parameters for each level of attributes, such as shown below:

&efq=brand:("...") OR gender:(“...”)
&efq=size:(“...”)
SKU-level efq and the facet response
Similar to product-level attributes, applying efq on a facet value will only return the applied value in the API response for that facet. Refer to the example given for product-level efq.

Syntax for fq and efq parameters

  • Surround attributes in your value with quotes. For example:
brand:"Fossil"
  • If the attribute in the efq parameter contains a space, surround the attribute with quotes. For example:
&efq="Product Type":"1"
  • For efq filters, surround the entire attribute value with parentheses. For example:
&efq=brand:("Fossil" OR "Betsey Johnson")
Parentheses are only required when using efq. Do not use parentheses with fq.
  •  If the value has quotes within it, then the quotes should be escaped with '\'. For example:
&fq=Sheet Dimension:"8.5\" x 11\""
&efq="Sheet Dimension":"8.5\" x 11\""
  • To apply filters for a ranged facet, such as price or sale price, the ranged value needs to be specified in addition to the product attribute.

           For example, to limit results to products with a price below 100:

&fq=price:[* TO 100]

           To limit results to products with a price between 200 and 300:

&fq=price:[200 TO 300]
Note: Ranged facets are not supported for efq.
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?