Python Developer Guide
Other documentationsDemoCommunityGitHub
  • Forest Admin
  • Getting started
    • How it works
    • Quick start
      • Flask
      • Django
    • Create your agent
    • Troubleshooting
    • Migrating legacy agents
      • Pre-requisites
      • Recommendations
      • Migration steps
      • Code transformations
        • API Charts
        • Live Queries
        • Smart Charts
        • Route overrides
        • Smart Actions
        • Smart Fields
        • Smart Relationships
        • Smart Segments
  • Data Sources
    • Getting Started
      • Collection selection
      • Naming conflicts
      • Query interface and Native Queries
        • Fields and projections
        • Filters
        • Aggregations
    • Provided data sources
      • SQLAlchemy
      • Django
        • Polymorphic relationships
    • Write your own
      • Translation strategy
        • Structure declaration
        • Capabilities declaration
        • Read implementation
        • Write implementation
        • Intra-data source Relationships
      • Contribute
  • Agent customization
    • Getting Started
    • Actions
      • Scope and context
      • Result builder
      • Static Forms
      • Widgets in Forms
      • Dynamic Forms
      • Form layout customization
      • Related data invalidation
    • Charts
      • Value
      • Objective
      • Percentage
      • Distribution
      • Leaderboard
      • Time-based
    • Fields
      • Add fields
      • Move, rename and remove fields
      • Override binary field mode
      • Override writing behavior
      • Override filtering behavior
      • Override sorting behavior
      • Validation
    • Hooks
      • Collection hook
      • Collection override
    • Pagination
    • Plugins
      • Write your own
    • Relationships
      • To a single record
      • To multiple records
      • Computed foreign keys
      • Under the hood
    • Search
    • Segments
  • Frontend customization
    • Smart Charts
      • Create a table chart
      • Create a bar chart
      • Create a cohort chart
      • Create a density map
    • Smart Views
      • Create a Map view
      • Create a Calendar view
      • Create a Shipping view
      • Create a Gallery view
      • Create a custom tinder-like validation view
      • Create a custom moderation view
  • Deploying to production
    • Environments
      • Deploy on AWS
      • Deploy on Heroku
      • Deploy on GCP
      • Deploy on Ubuntu
    • Development workflow
    • Using branches
    • Deploying your changes
    • Forest Admin CLI commands
      • init
      • login
      • branch
      • switch
      • set-origin
      • push
      • environments:create
      • environments:reset
      • deploy
  • Under the hood
    • .forestadmin-schema.json
    • Data Model
      • Typing
      • Relationships
    • Security & Privacy
Powered by GitBook
On this page
  • Condition trees
  • Examples
  • Structure
  • Operators
  • Operator equivalence
  • Paging
  • Examples
  • Search
  • Examples
  • Segments
  • Examples

Was this helpful?

  1. Data Sources
  2. Getting Started
  3. Query interface and Native Queries

Filters

This is the official documentation of the forestadmin-agent-django and forestadmin-agent-flask Python agents.

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" }
PreviousFields and projectionsNextAggregations

Last updated 1 year ago

Was this helpful?