Filtering

Almost all endpoints what returns list of data. Supports filter query parameter with paging combination.

Filter query parameter

filter=attribute|operation|value;attribute2|operation|value

Only specific properties support some filter groups.

Filter groups

Group

Operations

EQUALS

eq, ne

NUMBER

gt, gteq, lt, lteq

STRING

like

ENUM

in

BITS

bin, bex

Filter operations

Operation

Full name

Example

SQL representation

gt

Greater than

price|gt|499.9

price > 499.9

gteq

Greater than or equals

price|gteq|500

price >= 500

lt

Less than

price|lt|100

price < 100

lteq

Less than or equals

price|lteq|50

price <= 50

eq

Equals

type|eq|sale

type = 'sale'

ne

Not equal

type|ne|sale

type != 'sale'

like

Contains text (case insensitive)

name|like|text

name ILIKE '%text%'

in

Is in a set

externalId|in|3,5

externalId IN (3, 5)

notin

Is not in a set

externalId|notin|42

externalId NOT IN (42) OR externalId IS NULL

bin

Bits are set in a bit field

flags|bin|17

flags & 17 = 17

bex

Bits not set in a bit field

flags|bex|15

flags & 15 = 0

Filtering null values

To filter null or not null values a special keywords were introduced. They can be used in the filter in the place of a value.

Special value
Allowed with operators
Example
SQL representation

null

eq, ne, in, notin

externalId|eq|null

externalId IS NULL

notnull

eq, ne, in, notin

externalId|eq|notnull

externalId IS NOT NULL

Values null and notnull can be used together with custom filter values in filters, i.e externalId|notin|42,null will return only those entities with externalId not equal to 42 and not null at the same time.

The operators eq and ne are just a special case of operators in and notin respectively. It means that the results will be the same if you replace the in operator with eq when filtering a single value.

These special values cannot be used for the deleted attributes. See the next paragraph for more information.

Filtering deleted

There is a special behavior for filtering attributes deleted. The keywords "null" and "notnull" are not supported. The null values are considered as "not deleted" automatically, so there is no need to support null and not null filtering. If you ask the API to return not deleted entities only, it will automatically return entities with deleted false or deleted null. See the examples below.

For boolean attributes you can use 0 instead of false, and 1 instead of true.

Filter examples

Get only deleted items

filter=deleted|eq|true

Get all items (deleted and not deleted)

filter=deleted|in|0,1

Get items not deleted and those with deleted not set (is null) - this filter is used by default when no custom filter specified

filter=deleted|eq|false or filter=deleted|ne|true

Get items with externalId set to any non-null value

filter=externalId|eq|notnull

Get items with externalId not set (is null)

filter=externalId|eq|null

Get items with externalId not set or different from 3, 5, 7

filter=externalId|notin|3,5,7

Get items with externalId equal to 9 or not set (null)

filter=externalId|in|9,null

Get items with price from range <500, 1000>

filter=price|gteq|500;price|lteq|1000

Get items with created date in interval (left boundary - inclusive, right - exclusive)

filter=created|gteq|FROM;created|lt|TO

Last updated