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