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, ...).
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
With multiple conditions
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.
Of course, you can chain as many relations as you like.
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 supportBlank
,Missing
, andIn
if a field supports
LessThan
, it will automatically supportBefore
,BeforeXHoursAgo
andPast
... and so on
The minimal list of operators which is sufficient to have them all is the following:
In
andNotIn
(unlocksPresent
,Blank
,Missing
,Equal
, andNotEqual
)LessThan
andGreaterThan
(unlocks all dates operators)Like
(unlocksStartsWith
,EndsWith
, andContains
)NotContains
,LongerThan
,ShorterThan
, andIncludesAll
Paging
A paging clause tells the data source which page of the data should be retrieved.
Examples
Search
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 into current and linked collections:
Segments
The segment
field in a filter contains the name of the segment which is being targeted.
Examples
Last updated