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. 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.

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.

🚧

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.

🚧

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.

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

GET https://
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 syntax

Single value

• &fq=attribute:"value"

Multiple values

• &fq=attribute:"value 1" OR "value 2"

Escaping characters in fq

Escape these characters in your fq values:

fq use cases

#Searches for dresses that are red, purple, or red and purple
&q=dresses
&fq=color:"red" OR "purple"

#Searches for red dresses made by Rebel in Rose
&q=dresses
&fq=color:"red"
&fq=brand:"Rebel in Rose"

#Searches for dresses in category 1001
&q=dresses
&fq=category:"1001"

#Searches for dresses that are:
#1. red, purple, or red and purple
#2. in category 1001
#3. are size 10
#Only returns results that match all 3 filters
&q=dresses
&fq=category:"1001"
&fq=color: "red" OR "purple"
&fq=size: "10"

Ranged facets with facet.range

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

&facet.range=price

🚧

Note

Ranged facets are not supported for efq.

V3 Facet Response format: All the facets are unified under the facet object. To identify a range facet, use the identifier "type": "number_range".

Here's the corresponding response snippet, which shows you the count of items per sale_price range in the new facet format:

…
“facet_counts”: {
  "facets": [
      {
     "name": "sale_price",
      "type": "number_range",
      "values": [
        {
          "start": 0,
          "end": 5,
          "count": 5
        },
        {
          "start": 5,
          "end": 10,
          "count": 1
        },
        {
          "start": 10,
          "end": 20,
          "count": 1
        },
        {
          "start": 20,
          "end": "*",
          "count": 1
        }
      ]
    }

In the sample response snippet, the sale_price facet shows that there are five products priced $0 - $5, and one product each in the other sale_price ranges.

📘

Customers whose go-live date is after September 7, 2023 will be on V3 Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.

Legacy Facet Response format: The facet_fields section gives you facets that you can display to your site's users, such as brands and colors.

Here's the corresponding response snippet, which shows you the number of items per price 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.

📘

Default set of ranges for facet.range

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. 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.

Apply filters for a ranged facet

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.

&fq=price:[* TO 100]

&fq=price:[200 TO 300]

Hierarchical facets with facet.prefix

The facet.prefix parameter limits faceting to terms that start with the specified string prefix. Compare the following brand facet without and with facet.prefix:

This does not limit the query in any way, and only filters the facets that would be returned in response to the query.

facet.prefix can be useful to filter facets within a defined hierarchy. Compare the following sub-category facet without and with facet.prefix:

📘

facet.prefix compatibility

• Can be applied to these APIs:
  • Product Search
  • Category
  • Content Search
  • Search widget
  • Category widget
• Cannot be applied to SKU attributes.
• Cannot be applied to numeric/range facet types.
• Can be applied on the original names of fields, but not on the renamed names of fields.

To use prefix functionality on the Bloomreach-defined Category facet, you will need to make a few changes in the feed. Contact the Tech Services team for help with this use case.

facet.prefix syntax

Search APIs

• &f.facet name.facet.prefix=prefix to filter by

Widget APIs

• &facet.prefix=facet name:prefix to filter by

facet.prefix use cases

#Filters the brand facet by prefix “c”
&f.brand.facet.prefix=c

#Filters the brand facet by prefix “a”, and the color facet by prefix “re”
&f.brand.facet.prefix=a&f.color.facet.prefix=re

#For Widget APIs, filters the brand facet by prefix “c”
&facet.prefix=brand:c

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.

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.

📘

Difference between efq and 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.

📘

Supported APIs

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

efq operators

• OR: includes items that belong to any of the specified sets
• AND: includes items that belong to all of the specified sets
• NOT: excludes items that belong to any of the specified sets

efq syntax

OR

• Single attribute: &efq=attribute:("value 1" OR "value 2")
• Multiple attributes: &efq=attribute 1:("value") OR attribute 2:("value")

AND

• Single attribute: &efq=attribute:("value 1" AND "value 2")
• Multiple attributes: &efq=attribute 1:("value") AND attribute 2:("value")

NOT

• &efq=-attribute:("value")

Escaping characters in efq

Escape these characters in your efq values:

🚧

Parentheses: For efq, surround the entire attribute value with parentheses. Parentheses are only required when using efq. Do not use parentheses with fq.

Quotes: efq is not supported for any fields with spaces. If the facet name is multi-word, then it needs to be enclosed in quotes(" "). The syntax is: &efq="vessel size":("value")

👍

For efq facet names and facet values, you are allowed to use these special characters:

• Asterisk ( * )
• Underscore ( _ )
• Plus symbol ( + )
• Dot ( . )
• Dash ( - )

📘

NOT operator

Add the - before the attribute name, not the attribute value.

Correct: &efq=-Fabric:("Linen")
Incorrect: &efq=Fabric:("-Linen")

efq use cases

#Returns all Cotton items and all Linen items
&efq=Fabric:("Cotton" OR "Linen")

#Returns all Cotton items and all Red items
&efq=Fabric:("Cotton") OR Color:("Red")

#Returns all items that are both Cotton and Linen
&efq=Fabric:("Cotton" AND "Linen")

#Returns all items that are both Cotton and Red
&efq=Fabric:("Cotton") AND Color:("Red")

#Returns all Cotton Items that are not also Linen
&fq=Fabric:"Cotton"
&efq=-Fabric:("Linen")

Suppose we have four products with the following attributes:

These are the products that would be returned for each set of operations:

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.

 …
“facet_counts”: {
  "facets": [
{
      "name": "styles",
      "type": "text",
      "value": [
    {
      count: 81,
      name: "Tea dress"
    }
  ]
}

…
“facet_counts”: {
  "facets": [
{
      "name": "styles",
      "type": "text",
      "value": [
    {
      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"
    }
  ]
}

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

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"
    },
  ]
}

📘

Customers whose go-live date is after September 7, 2023 will be on V3 New Facet response format by default. If you’re on the legacy format and would like to implement the new Facet response format, kindly contact your Bloomreach Services representative.

SKU-level efq

efq can also be applied at the SKU level.

#Returns all Cotton SKUs and all Linen SKUs
&efq=Material:("Cotton" OR "Linen")

#Returns all Cotton SKUs and Red SKUs
&efq=Material:("Cotton") OR Sku_color:("Red")

#Returns all SKUs that are available in both Cotton and Linen
&efq=Material:("Cotton" AND "Linen")

#Returns all SKUs that are available in both Cotton and Red
&efq=Material:("Cotton") AND Sku_color:("Red")

#Returns all SKUs that are not available in Cotton
&efq=-Material:("Cotton")

Suppose we have four SKUs with the following attributes:

These are the SKUs that would be returned for each set of operations:

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:

#brand and gender are both product-level attributes, so this is valid
&efq=brand:("...") OR gender:(“...”)
#brand is a product-level attribute and size is a SKU-level attribute, so this is not valid
#Will return a 400 error response
&efq=brand:("...") OR size:(“...”)

{
    "status_code": 400,
    "message": "[u'Malformed efq param: -(sku_size:(\"11-12 years\" OR \"10-11 years\")) OR price:\"39\"']"
}

&efq=brand:("...") OR gender:(“...”) #Product-level attributes
&efq=size:(“...”) #SKU-level attributes

📘

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.