🚧

Warning

Utilizing pre-filter expressions is advanced functionality that should be carefully considered before proceeding. Please discuss utilizing pre-filter expressions with your technical integration contacts, as doing so may have unintended consequences to integration health.

Pre-filter expressions allow users to apply specific criteria to requests to retrieve product data (for example, Search and Browse requests), refining results based on predefined preferences or requirements. This parameter allows for the application of an arbitrary boolean expression to filter results for product listings based on specific criteria before they are presented to the user.

It is particularly useful in scenarios where users have known preferences or where the context of the request needs to be narrowly defined to improve relevance and efficiency. This document outlines the scope & use-cases of the pre_filter_expression parameter.

For a more detailed technical specification of the schema, please refer to Filter expressions

Application and scope

When applied, a pre_filter_expression sets the scope of a request. This means that only items matching the expression will be returned in the response. Items that do not match the pre_filter_expression are excluded from the outset, making them completely out of scope for the request. This is a key distinction from regular filters, which are applied after the query has been executed and do not influence the initial scope of the search. This approach has significant implications for facet counting and the overall user experience.

By pre-filtering the results, the pre_filter_expression ensures that facets (that is, filterable attributes such as color, size, brand) are only counted and displayed if they are relevant to the pre-filtered set of items. This leads to a more streamlined and relevant browsing experience, as users are not presented with filter options that are irrelevant to their search context. In contrast, user-selected filters do not have the same impact.

For example, if a user selects Brand: XYZ, while Constructor filters results for this particular brand, we also want to show other brands as selectable filters (along with their match counts), so that the user has the possibility to add additional brands to their search. However, items that don't match the pre_filter_expression, are not considered at all, so they do not contribute to facet counts & they are not discoverable in that given context.

Advantages

Efficiency and time-saving

By applying known preferences or context-specific criteria upfront, pre_filter_expression saves users time by immediately narrowing down the search results to items of interest, eliminating the need for manual filtering through potentially irrelevant results.

Enhanced relevance

The ability to define complex filtering logic ensures that the search results are highly relevant to the user's needs and preferences, improving the overall effectiveness of the search.

Flexibility

The arbitrary boolean expression format offers unparalleled flexibility in defining the filtering logic, allowing for the combination of multiple criteria in ways that standard filtering options cannot accommodate.

Use cases

pre_filter_expression is particularly useful in scenarios where the user's preferences are known in advance or where the search needs to be constrained by specific criteria to ensure relevance. For example:

• An e-commerce platform could use pre_filter_expression to implement a feature that allows users to search for products within their preferred size, color, and brand parameters automatically applied based on their profile settings.
• A B2B site could use pre_filter_expression to constrain the search of different client accounts in scenarios when certain items are only available to some clients.