Faceting and filtering - Bloomreach Experience - Open Source CMS

Faceting and filtering

Simple filtering

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, such as a price or sale price. The specified facets are returned with a default set of ranges:

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

If you want to change your default ranges, you can access the Facet Management tool in the Bloomreach dashboard to do so. You can refer to directions on how to do that 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.

Specifying price and sale price ranges

The facet.range parameter returns counts for a set of default ranges. While facet.range can returns counts for any numeric field, price and sale_price are the typical fields for this parameter.

This parameter retrieves products according to default ranges. During integration, your Bloomreach TPM can change these defaults for you. After integration, you can change these defaults by contacting your Bloomreach CSM. Here are the default ranges:

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

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

The facet.range parameter differs from the fq parameter. 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.

Requesting counts for a set of ranges is easy: just append the facet.range parameter to your call with a value of price or sale_price:

&facet.range=sale_price

or

&facet.range=price

Here's an example response snippet for &facet.range=price:

Response snippet 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

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.

efq operators 

Operator Purpose Example

OR

 

Expands results to include all items that belong to any specified set.
&efq=fabric:("cotton" OR "linen")

Returns a set of all cotton items and all linen items.

 

Returned:

  • 80% linen, 20% cotton dress
  • 100% linen suit

Not returned: 50% cashmere, 50% silk sweater

AND

 

Limits results to include only items that belong to all specified sets.
&efq=fabric:("cotton" AND "linen")

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

 

Returned: 80% linen, 20% cotton dress

 

Not returned:

  • 80% cotton, 20% acrylic sweater
  • 100% linen suit

 

---  Expands or limits results to include all items that belong to specified sets, except those that also belong to other specified sets.
&fq=fabric:"cotton"

&efq=-fabric:("linen")

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

 

Returned:

  • 80% cotton, 20% acrylic sweater
  • 100% cotton shirt

Not returned: 80% linen, 20% cotton dress

Tip 

Preface the excluded attribute with the - operator, not the attribute value.

Correct: -fabric:"linen"

Incorrect: fabric:-"linen"

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:

            "Product Type":"1"

  • If you have multiple values, then surround the entire value with parentheses. For example:

            brand:("Fossil" OR "Betsey Johnson")

Please note that if the value has quote within it, then the quote should be escaped with '\', e.g. Sheet Dimension = 8.5" x 11".
  • In this case the fq should be: Sheet Dimension:"8.5\" x 11\""
  • In this case the efq should be: "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:

            price:[* TO 100]

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

           price:[200 TO 300]

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?