Skip to content

README.md

Latest commit

 

History

History
98 lines (76 loc) · 5.45 KB

README.md

File metadata and controls

98 lines (76 loc) · 5.45 KB

Learn how to filter data

This guide shows how to filter data with Hatchify.

Using the filters

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.

Operators

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.

Compatibility

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

Omitted Operators

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)

Further information

Hatchify is using @bitovi/querystring-parser to parse querystrings. More information on query styles and other options is available here.