Filtering logic overview

2025-04-03

Important

Azure Intelligent Recommendations Retirement and Migration Plan

Azure Intelligent Recommendations will be retired on March 31, 2026.

We're retiring the product due to changes in strategy and focus with the onset of the copilot era. Currently, there are no equivalent services available within the Microsoft stack, so we can't offer a migration plan to a similar service.

Next steps:

Identify or build an alternative.
Migrate all your traffic to the chosen alternative.
Stop calling the Recommendations endpoint before the shutdown date.
Delete all service endpoints, modeling, and IR accounts in the Azure portal before the shutdown date.

We'll continue to monitor and maintain Azure Intelligent Recommendations during the retirement period. After the product is retired, we'll keep the service data for three months before deleting it.

Item filtering is one of the most important capabilities in the Intelligent Recommendations service. Filters help to narrow down thousands of items based on certain customizable parameters such as size, color, category, price, etc. and only return items that meet the needs and interests of the end-user.

This document describes the filtering solution for Intelligent Recommendations and has the following sections:

Section title	Overview
Filtering capabilities	The filtering logical operations that we support.
Data schema	The data contract for defining filters on product items and variants.
API	The filtering query language of our runtime service.

You should ensure that the data schema and API is well documented, strict, and is as simple as possible for a good customer (end-user) experience.

Filtering capabilities

You can set filter values per item/variant, and based on those values, query the Intelligent Recommendations runtime service API with different filter operators. For more information, see Data Schema section.

The Intelligent Recommendations service currently supports the following filter operators:

Equal

Equal operator logic

Let D be the set of filter values defined for an item X, and ‘a’ be the API requested value.
X will pass the filter if and only if  a∈D.

Examples:

Item values (D)	API value (a)	Satisfied
{Blue, Black, Red}	Red	True
{Blue, Black}	Red	False
∅	Red	False

Multi-value logic

This section covers the AND, OR, Range, and Availability operator logic rules.

Operator logic for AND/OR

Operator	Definition
AND	`Let A be the API requested set of values, X will pass the filter iff A ⊆ D`
OR	`Let A be the API requested set of values, X will pass the filter if and only if A∩D ≠∅`

Additional notes:

Supports case insensitive strings.
Boolean values are represented by ‘true’ and ‘false’ strings.

Examples of AND/OR logic

Logical operator	Item values (D)	API values (A)	Satisfied
OR	{Blue, Black, Red}	{Green, White}	False
OR	{Blue, Black, Red}	{Green, Blue}	True
AND	{Blue, Black, Red}	{Green, Blue}	False
AND	{Blue, Black, Red}	{Red, Blue}	True

Range

The operator supports numeric values only and is satisfied if and only if at least one of the item filter values is within the API requested range.

Special cases:
- Greater than (or equal to)
- Less than (or equal to)

Examples of Range filtering

values	API Range	Satisfied
{2,9,23}	5 <= value < 15	True
{50,128}	128 < value	False

Availability filter

This filter is a special time-based filter that filters out all items that are outside of the availability time range. The availability time range is defined per item in the availabilities data schema. This filter will always run by default.

Data Schema

The Intelligent Recommendations service allows you to define up to 20 different filters. You can use the following data schema to define filter values on your product items (for more information, see our Catalog Data Entity Guide for Filters):

Name	Data type	Mandatory	Comments
ItemId	String	Yes
ItemVariantId	String	No
FilterName	String	Yes	Length limited to 64 characters.
FilterValue	String	Yes	Length limited to 64 characters.
FilterType	String	Yes	Possible values - Textual, Numeric.

Item master and item variants

An item (or master item) may have a one-to-many relationship with its item variants.
A variant inherits all attributes of its master by default. You can override an attribute by declaring it explicitly, as shown in the example.

For multi-value filters, you should provide multiple rows with single value, each row with a different value.

Example:

ItemId	ItemVariantId	FilterName	FilterValue	FilterType
Item1	Color	Red	Textual
Item1	Item1Var1	Color	Blue	Textual
Item1	Item1Var1	Color	Black	Textual
Item1		Size	38.0	Numeric

In this example, Item1 is the master item and has one color Red and one size 38.0. Item1Var1 is a variant of Item1 and has two colors: Blue and Black (overridden values) and one size – 38.0 (inherited value).

API

The Intelligent Recommendations filtering API is based on Microsoft REST API Guidelines.

$filter is the URL parameter, which contains the full query Boolean expression. The expression specified with $filter is evaluated for each item, and only items where the expression evaluates to true are included in the response.

[Note!]

Only filters that match by name (case insensitive) to one of the FilterName values (from data schema) and has an appropriate FilterType (textual/numeric) for the requested filter operation, will be executed. The rest will be ignored.

An Item master will return if the expression evaluates to true for its own filter values OR for one of its variants.

The following table describes the supported filter operators:

Operator	Type	Operator	Description
Comparison	eq	Equal	color eq 'red'
Comparison	gt	Greater than	size gt 34
Comparison	ge	Greater than or equal	size ge 36
Comparison	lt	Less than	size lt 42
Comparison	le	Less than or equal	size le 40
Logical	and	Logical and	size le 44 and size gt 38
Logical	or	Logical or	color eq ‘red’ or color eq 'blue'
Grouping	( )	Precedence grouping	(color eq ‘red’ or color eq 'blue') and size gt 38

URL Examples:

Reco/v1.0/New?$filter=color eq ‘Red’
Reco/v1.0/Popular?$filter=color eq ‘Red’ and size lt 40
Reco/v1.0/Picks?$filter=(name eq ‘Red’ or name eq 'Blue') and size le 44 and size gt 38

[!Note]

URL encoding is required.

Supported scenarios

AND logical operator between different filters.
OR operator between different values of the same filter. Error handling – for an unsupported query, the service returns a bad request HTTP status (400).