When collections can be filtered you may pass one or more filter query parameters. The syntax for these filters
is described below.
Basic Syntax (Equals)
The most basic filter is of the form key:value where key is the name of the field to filter by and value
is a literal string or integer. This basic filter applies the logic “where equals ''”.
| Query | Description |
|---|
?filter=id:15 | id equals 15 |
?filter=status:complete | status equals ‘complete’ |
?filter=is_active:true | boolean values true and false supported |
Multiple filters can be specified in which case they are combined with a logical AND operation.
| Query | Description |
|---|
?filter=id:15&filter=status:complete | id equals 15 AND status equals ‘complete’ |
This basic syntax can be mixed with the advanced syntax described below.
Advanced Syntax
The advanced syntax is of the form key<json> where key is the field name and <json> is a valid JSON5 encoded
object or array of objects. These objects can define a broad variety of conditions defined further below.
There is no : between the key and the <json>!
| Query | Description |
|---|
?filter=id{gt:15} | id greater than 15 |
AND Logic
Multiple conditions can be applied with AND logic for the same key by specifying multiple keys in the same JSON5 object.
| Query | Description |
|---|
?filter=id{gt:15,lt:50} | id greater than 15 AND less than 50 |
OR Logic
Multiple conditions can be applied with OR logic for the same key by specifying an array of objects.
| Query | Description |
|---|
?filter=id[{lt:15},{gt:50}] | id less than 15 OR greater than 50 |
Combined AND and OR logic
Both AND and OR logic can be used in the same filter.
| Query | Description |
|---|
?filter=weight[{gt:1,lt:50},{null:true}] | weight is either greater than 1 AND less than 50 OR weight is null |
Multiple filters with advanced and simple syntax mixed
?filter=goods_type:NORMAL&filter=name[{start:"Box of"},{end:"CASE"}]&filter=id{gt:15}
Conditions
The following keys may be used within the JSON5 object to apply the described conditions.
| key | Condition | Examples | Comment |
|---|
| eq | Equal to | {eq:5}
{eq:"John Doe"}
{eq:true} | |
| neq | Not equal to | {neq:5}
{neq:"John Doe"}
{eq:true} | |
| gt | Greater than | {gt:5} | |
| lt | Less than | {lt:5} | |
| gteq | Greater than or equal | {gteq:5} | |
| lteq | Less than or equal | {lteq:5} | |
| from | From date or date-time | {from:"2021-11-17"}
{from:"2021-11-17T14:32:44Z"} | Specifying a date for a date-time value will be equivalent to “greater than or equal to YYYY-MM-DDT00:00:00Z” (inclusive) |
| to | To date or date-time | {to:"2021-11-17"}
{to:"2021-11-17T14:32:44Z"} | Specifying a date for a date-time value will be equivalent to “less than or equal to YYYY-MM-DDT23:59:59Z” (inclusive) |
| start | Starts with | {start:"John"} | Prefix match (like John*) |
| end | Ends with | {end:"Doe"} | Suffix match (like *Doe) |
| contain | Contains anywhere | {contain:"Baker"} | Anywhere match (like *Baker*) |
| regex | Matches regular expression | {regex:"^A.+Z$"} | See MySQL Regular Expression Syntax |
| iregex | Matches regular expression (case insensitive) | {regex:"^A.+Z$"} | See MySQL Regular Expression Syntax |
| in | Equals a value in the set | {in:[1,2,3,4]}
{in:["canceled","processing"]} | |
| nin | Not equal to any value in the set | {nin:[1,2,3,4]}
{nin:["canceled","processing"]} | |
| null | Value is or is not NULL | {null:true}
{null:false} | |
| empty | Value is or is not NULL or equal to an empty string | {empty:true}
{empty:false} | true is equivalent to {eq:""},{null:true} and false is equivalent to {neq:"",null:false} |
String values must be "double-quoted" or 'single-quoted'.
