Filtering

The filtering language is a simple expression language that accepts a filter string, and evaluates to either true or false. The filter is passed as a filter query parameter and must be URL encoded.

Logical Expressions

The smallest building block of a filter string is a logical expression. The simplest filter string consists of a single logical expression.

A logical expression takes the form:

property operator value

Property

A property represents a field in the resource being filtered, and will always be wrapped in { and } braces.

Operator

Operators are 2-character symbols representing a comparison. The full list of supported operators is in the Supported Comparison Operators section below.

Value

A value represents the scalar value that the operator is testing the property against. A value will always be wrapped in [ and ] brackets.

Example: Item's SKU equals ABC

https://api.stok.ly/v0/items?filter={item.sku}==[ABC]

The filtering engine returns true if the item's SKU is "ABC".

Boolean Operators

Logical expressions can be chained together using boolean operators:

logical_expression boolean_operator logical_expression

The supported boolean operators are listed in the Supported Boolean Operators section below.

Example: Item's SKU equals ABC and item's name contains XYZ

https://api.stok.ly/v0/items?filter={item.sku}==[ABC]&&{item.name}::[XYZ]

The filtering engine returns false if the SKU matches but the name does not contain "XYZ".

If the boolean operator were changed to || (or), the result would be true, because at least one expression is satisfied.

How it works: Each logical expression is evaluated independently to true or false. The boolean operator then determines the overall result:

• && (and) — requires all expressions to be true
• || (or) — requires at least one expression to be true

Brackets

Brackets group expressions that should be evaluated together before the rest of the filter. The bracketed portion is resolved as its own filter string first, then combined with the outer result.

Example:

https://api.stok.ly/v0/items?filter={item.sku}::[ABC]&&({item.type}==[A]||{item.type}==[B])

This matches any item whose SKU contains "ABC" and whose type is either A or B.

Supported Comparison Operators

Supported Boolean Operators

Type Annotations

In newer versions of the filtering language, you can specify the type of a value using the syntax @type; inside the value brackets.

Supported types:

Example: Match any order where the country has not been set

https://api.stok.ly/v2/saleorders?filter={order.country}::[@null;]

Example: Match any item whose price is less than its RRP

https://api.stok.ly/v2/saleorders?filter={item.price}<<[@property;item.recommendedPrice]

Instead of comparing against a literal value, @property; tells the engine to resolve the value as another field from the resource.