This guide shows how to filter data with Hatchify.
Hatchify's middleware supports a wide variety of filtering capabilities. For example, the following url might find all todos whose name starts with "clean":
GET /api/todos?filter[name][$ilike]=clean%25
Note:
%25
is%
escaped.
These queries are also supported in react-rest:
Todo.useAll({
filter: {
name: { $ilike: "clean%" },
},
})
Filters can be combined across multiple properties:
Todo.useAll({
filter: {
name: { $ilike: "clean%" },
severity: { $gt: 0.5 },
user: { name: "Christina" },
},
})
Filter queries take the shape of: filter[ATTRIBUTE_NAME][OPERATOR]=VALUE
.
The following operators are supported for filtering. Click on each one to see compatibility and example usage.
Operator | Description |
---|---|
$eq |
Matches values that are equal to the given value. |
$ne |
Matches values that are not equal to the given value. |
$gt |
Matches if values are greater than the given value. |
$gte |
Matches if values are greater or equal to the given value. |
$lt |
Matches if values are less than the given value. |
$lte |
Matches if values are less or equal to the given value. |
$in |
Matches any of the values in an array. |
$nin |
Matches none of the values specified in an array. |
$like |
%foo → ends with foo foo% → starts with %foo% → contains foo → equals |
$ilike |
%foo → ends with foo (insensitive) foo% → starts with (insensitive) %foo% → contains (insensitive) foo → equals (insensitive) |
omitted operator | behavior varies, see table in Omitted Operators section below. |
Operators will only work on specific value types (string, number, boolean, date).
Operator | String | Date | Boolean | Numeric | UUID | Arrays |
---|---|---|---|---|---|---|
$eq |
✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$ne |
✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
$gt |
✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
$gte |
✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
$lt |
✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
$lte |
✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
$in |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$nin |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
$like |
✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
$ilike |
✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
no operator | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
If no operator is present, then $eq
is used.
Value Type | Example | Operator Equates to |
---|---|---|
string | filter[name]=lisa |
$eq |
number | filter[age]=25 |
$eq |
date | filter[born]=2020-01-01 |
$eq |
null | filter[score]=%00 |
$eq |
boolean | filter[completed]=false |
$eq |
uuid | filter[uuid]=e33a8fbd-bf2f-4348-9091-8e1b6b659b69 |
$eq |
array | filter[name]=mike&filter[name]=brad |
$in (with $eq) |
Hatchify is using @bitovi/querystring-parser
to parse querystrings. More information on query styles and other options is available here.