Links

Filters

A filter represents a subset of records within a collection. As such, a filter always exists in the context of a given collection.
It is used to restrict the records which will be targeted by specific actions (list, update, aggregate, ...).
{
// Condition tree
"conditionTree": { "field": "createdAt", "operator": "today" },
// Paging
"page": { "limit": 30, "skip": 0 },
"sort": [
{ "field": "title", "ascending": true },
{ "field": "id", "ascending": true }
],
// Search [advanced]
"search": "John Smith",
"searchExtended": false,
// Segment [advanced]
"segment": "Active Records"
}
This is quite complex! Let's break it down into small understandable pieces.

Condition trees

A condition tree, as its names imply, is a set of conditions that applies to the records themselves and tells which records should be included or excluded from a given query.

Examples

Simple condition tree

{ "field": "title", "operator": "StartsWith", "value": "Found" }

With multiple conditions

{
"aggregator": "And",
"conditions": [
{ "field": "title", "operator": "Equal", "value": "Foundation" },
{ "field": "subTitle", "operator": "Equal", "value": "The Psychohistorians" }
]
}

With relationships

one-to-one and many-to-one relationships are supported.
In this example, we want to apply a condition tree to a related field value.
{ "field": "book:title", "operator": "Equal", "value": "Foundation" }
Of course, you can chain as many relations as you like.
{ "field": "book:price:value", "operator": "Equal", "value": 15 }

Structure

Each node of a condition tree can be one of five things:
  • An "And" branch: { aggregator: 'And', conditions: [<otherNodes>] }
  • An "Or" branch: { aggregator: 'Or', conditions: [<otherNodes>] }
  • A "condition" leaf without parameter: { field: 'title', operator: 'Present' }
  • A "condition" leaf with parameter: { field: 'title', operator: 'Equal', value: 'Foundation' }

Operators

Here is the list of operators which are supported by Forest Admin.
Operator
Types
Expected parameter
Present
All
Blank
All
Missing
All
Equal
All but array
Field type
NotEqual
All but array
Field type
LessThan
All but array
Field type
GreaterThan
All but array
Field type
In
All but array
Array of field type
NotIn
All but array
Array of field type
Matches
String
String
ILike
String
String
Like
String
String
StartsWith
String
String
EndsWith
String
String
Contains
String
String
NotContains
String
String
LongerThan
String
Number
ShorterThan
String
Number
Before
Date
Date
After
Date
Date
AfterXHoursAgo
Date
Number
BeforeXHoursAgo
Date
Number
Past
Date
Future
Date
PreviousMonthToDate
Date
PreviousMonth
Date
PreviousQuarterToDate
Date
PreviousQuarter
Date
PreviousWeekToDate
Date
PreviousWeek
Date
PreviousXDaysToDate
Date
Number
PreviousXDays
Date
Number
PreviousYearToDate
Date
PreviousYear
Date
Today
Date
Yesterday
Date
IncludesAll
Array
Array

Operator equivalence

You may have noticed that many operators overlap. To make data sources quicker to implement, Forest Admin supports automatic operator replacement.
What that means is that when an operator can be expressed using a combination of other operators, Forest Admin will perform the substitution automatically using the following table.
Operator
Automatic replacement
Present
NotEqual null and NotEqual ""
Blank
Equal null or Equal ""
Missing
Equal null
Equal
In [$value]
NotEqual
NotIn [$value]
In
Equal $value or Equal $2 or ...
NotIn
NotEqual $value and NotEqual $2 and ...
StartsWith
Like '$value%'
EndsWith
Like '%$value'
Contains
Like '%$value%'
Before
LessThan $value
After
GreaterThan $value
AfterXHoursAgo
GreaterThan $hoursAgo($value)
BeforeXHoursAgo
LessThan $hoursAgo($value)
Past
LessThan $now
Future
GreaterThan $now
PreviousMonthToDate
GreaterThan $startOfMonth & LessThan $now
PreviousMonth
GreaterThan $startOfLastMonth & LessThan $endOfLastMonth
PreviousQuarterToDate
GreaterThan $startOfQuarter & LessThan $now
PreviousQuarter
GreaterThan $startOfLastQuarter & LessThan $endOfLastQuarter
PreviousWeekToDate
GreaterThan $startOfWeek & LessThan $now
PreviousWeek
GreaterThan $startOfLastWeek & LessThan $endOfLastWeek
PreviousXDaysToDate
GreaterThan $xDaysAgo($value) & LessThan $now
PreviousXDays
GreaterThan $xDaysAgo($value) & LessThan $startOfToday
PreviousYearToDate
GreaterThan $startOfYear & LessThan $now
PreviousYear
GreaterThan $startOfLastYear & LessThan $endOfLastYear
Today
GreaterThan $startOfToday and LessThan $endOfToday
Yesterday
GreaterThan $startOfYesterday and LessThan $endOfYesterday
In practice:
  • if a field supports Equal, it will automatically support Blank, Missing, and In
  • if a field supports LessThan, it will automatically support Before, BeforeXHoursAgo and Past
  • ... and so on
The minimal list of operators which is sufficient to have them all is the following:
  • In and NotIn (unlocks Present, Blank, Missing, Equal, and NotEqual)
  • LessThan and GreaterThan (unlocks all dates operators)
  • Like (unlocks StartsWith, EndsWith, and Contains)
  • NotContains, LongerThan, ShorterThan, and IncludesAll

Paging

A paging clause tells the data source which page of the data should be retrieved.

Examples

{
"page": { "limit": 30, "skip": 0 },
"sort": [
{ "field": "title", "ascending": true },
{ "field": "id", "ascending": true }
]
}
The search field is a simple filter that the final user types in the search bar in the admin panel, and can be used to restrict records.
Likewise searchExtended boolean is an action that can be triggered by end-users and its implementation can vary between data sources.
For instance, in @forestadmin/datasource-sql, the searchExtended flag is used to also search content into all collections which are linked with a many-to-one or one-to-one relation to the current one.

Examples

Search into the current collection:
{ "search": "Isaac", "searchExtended": false }
Search into current and linked collections:
{ "search": "Isaac", "searchExtended": true }

Segments

The segment field in a filter contains the name of the segment which is being targeted.

Examples

{ "segment": "Active records" }