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 |
Info
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.
Info
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.
Warning
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.
Info
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 |
|
| 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 |