Filters

This is the official documentation of the @forestadmin/agent Node.js agent.

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 }
  ]
}

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": "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" }