Filtering on Item Property¶

At times, you may want to have recommendations on items satisfying certain criteria: a price range, the release year of a movie, a minimal popularity, some internal business rule… Filters are provided for this task, enabling your client to dynamically preselect items based on their properties. They are a type of business rules.

Naturally, the richer the items properties, the better the filter, but that’s only the tip of the iceberg since this feature is useful at two different levels:

You can create server-side business rules, such as displaying only new TV-shows in some sections of your app.
You can hand over control to your end user with buttons and switches, so they can configure themselves what they see. Think price range, clothes’ color, category, brand or platform.

Keep in mind that each filter applies to only one item-property; you can then combine multiple filters together, resulting in the intersection of all.

Below, we first present the syntax of filters (the two ways to use them) before moving on to their logic to see what each filter operator does and how to combine them.

Filter Syntax¶

There are two equivalent ways to format a filter: either using a JSON object or using a URL-compatible string.

JSON Object Format¶

The JSON object defining a filter is formed by the following fields:

property_name: the item-property name on which you want to filter
op: the filter operator (case insensitive). Available operators are defined below in Filter Logic
value: the optional value for the operator. Depending on the operator, this field is either omitted or compulsory. When required, the value type depends on the item-property type (scalar/string) and on the operator (single scalar/string or list thereof).

URL-Compatible Format¶

The equivalent syntax is also allowed. This is particularly useful to send the filters as URL query parameters.

<PROPERTY_NAME>:<OP>

for operators without value, or

<PROPERTY_NAME>:<OP>:<VALUE>

for operators with a value.

Do remember to use percent-encoding when using reserved characters as values.

Examples¶

For instance this filter enforces recommendations of only items with a price strictly less than 10.

URL-string version: price:lt:10.

Object version:

{
  "property_name": "price",
  "op": "lt",
  "value": 10
}

This other filter enforces recommendations of only items with either the tag family or the tag fiction.

URL-string version: tags:in:family,fiction.

Object version:

{
  "property_name": "tags",
  "op": "in",
  "value": ["family", "fiction"]
}

This third filter enforces recommendations of only items which contain at least a value in the property actors.

URL-string version: actors:NotEmpty (operators are case-insensitive).

Object version:

{
  "property_name": "actors",
  "op": "NotEmpty"
}

Filter Logic¶

You will find below the table of all operators and a detailed description of the filtering logic.

Operators Table¶

The API implements the following operators.

Operator	Value	Description	Quantifier for Repeated Property
`eq`	scalar	equal to value	`exists`
`lt`	scalar	strictly less than value	`exists`
`lte`	scalar	less or equal to value	`exists`
`gt`	scalar	strictly greater than value	`exists`
`gte`	scalar	greater or equal to value	`exists`
`in`	list	equal to one of the values	`exists`
`neq`	scalar	not equal to value (or null)	`forall`
`notin`	list	not equal to any of the values (or null)	`forall`
`notempty`	none	not null	`exists`

Note that not all operators are available for all property types. For instance floating point properties suffer from precision issues and therefore cannot be filtered using equality. Please refer to Property Types to find if an operator is available.

Quantifier for Repeated Property¶

For repeated properties, such as a list of many tags, most operators follow the exists set quantifier. This means that the API will return items where at least one of the repeated values satisfies the operator.

For instance by using the filter tags:eq:family the API may return items with {"tags": ["action", "family"]} or {"tags": ["family"]}, but will not return any item with {"tags": []} or {"tags": ["action"]}.

Two operators do not follow this logic and instead implement the forall set quantifier: neq and notin. For these operators all repeated values must satisfy the operator.

For instance by using the filter tags:notin:family,drama the API may return items with {"tags": []} or {"tags": ["action", "comedy"]}, but will not return any item with {"tags": ["action", "family"]} or {"tags": ["action", "drama"]}.

This logic is only relevant for repeated properties because on a set of size 1, exists and forall are equivalent.

Combining Rules¶

By combining multiple filters you can achieve complex business rules.

Multiple Filters¶

When using multiple filters, the API will return items that satisfy all filters.

For instance using both price:gte:4 and price:lte:10 together will return only items with a price between 4 and 10.

Putting Everything Together¶

By default the operators neq or notin also return items with empty sets for this property. You may want to also exclude these items without the property. You can achieve this by adding a notempty filter on the same property.

When using multiple filters on the same repeated property, each filter is considered independently. Combining all the above logic is a great tool to generate complex business rules, but it can also produce un-intuitive filtering with repeated integers. For instance, an item with {"scores": [1, 2, 3, 4]} satisfies the filters scores:gt:3 & scores:lt:2.