> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering Syntax

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 {key} equals '{value}'".

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

> [!NOTE]
>
> 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](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#regexp-syntax) |
| iregex | Matches regular expression (case insensitive) | `{regex:"^A.+Z$"}` | See [MySQL Regular Expression Syntax](https://dev.mysql.com/doc/refman/8.0/en/regexp.html#regexp-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}` |

> [!NOTE]
>
> String values must be `"double-quoted"` or `'single-quoted'`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.