Filters allow you to conditionally select Items from a Collection. Use-cases include customizing Item search results, restricting Item access permissions for specific Users or Roles, building dashboard analytics with the Insights module, and more.
There Are Two Filters Documents
This page is a non-technical guide to using Filters. For more technical info, see Filter-Rules.
How it Works
Filters are intuitive to use, but get quite nuanced as complexity increases. In order to use Filters effectively, you will need to understand the Field (aka data model) being filtered as well as any relevant Users, Roles and Permissions.
A basic filter is composed of 3 parts: A Field from the Collection being Filtered, a logical Operator, and some specified Value to filter for within each Item's Field.
- Click filter_list or "Add Filter".
- Select the Field to filter by.
- Select the Operator as desired.
- Define the Value to filter for.
The Field type will determine the kinds of Operators that can be used on it. In fact, some Fields cannot be filtered at all (read more in Unfilterable Fields). Once a Field is selected, the permitted operators will automatically display. An exhaustive list of Operators and what they do can be found in the more technical Filter Rules document.
AND Groups give the option to filter for Items that meet all of several criteria. On the other hand,
OR Groups filter for Items that meet any one of several criteria.
- Click "Add Filter".
- Click "And/OR Group" at the very top of the dropdown menu.
- Click the AND/OR text to toggle:
AND– Selects Items that meet every single criteria.
OR– Selects Items that meet one of several criteria.
- Click "Add Filter" again.
- Configure the Field, Operator, and Value as desired.
- Click and hold drag_indicator to drag a Filter and nest it under an AND/OR Group.
Why do we need AND Groups?
Filters actually default to
AND Group behavior automatically. However, when Filters are nested inside of an OR Group, they of course switch to
OR Group behavior. So an AND Group is necessary in cases where you want to meet multiple conditions inside of OR Groups.
The following video shows how to filter for Blog posts written within the past 60 days.
The following Dynamic Variables are built into Directus to make Filtering easier:
$NOW(<adjustment>). For more information, please see the Dynamic Variables section in Filter Rules.
Filtering by Related Collections
You may need to run filters on one Collection based on information in another related Collection. Here are a few examples of when that might happen:
- Book authors that also wrote screenplays (filters
- Products with a 5 star customer review (filters
- Accounts with active user login within the last 12 months (filters
This can span across any number of relationally linked Collections. For example, you could filter for customers that bought rock songs, where the
genres Collections are linked by
You will notice a chevron_right icon beside relational Fields. When you click on any Alias Field, all the Fields for that associated Collection pop down. If you select one of these Fields, you can run Filters on the current Collection by Field values in a related Collection.
Here are step-by-step instructions on how to filter by Fields in other Collections:
- Click "Add Filter".
- Click the desired relational Field. This will pop down and display the related Collection Fields.
- Select a Field from this related Collection.
- Set the Operator and Value as desired.
Not all Fields can be filtered. As seen above in Filtering by Related Collections, Alias Fields cannot be filtered; they instead provide a dropdown menu to access Fields from a related Collection. Additionally, the "Presentation" and "Group" Fields cannot be filtered at all and will not appear as an option in Filters.
Directus Core is completely open-source, modular and extensible. Extensions allow you to expand or modify any part of Directus to fit your needs. Here are some great resources to get started down that track.
- Extensions > Introduction
- Extensions > Creating Extensions
- Contributing > Introduction
- Contributing > Codebase Overview
Working on an enterprise project and looking to outsource or financially sponsor the development of a Shares extension? Contact our team
Looking for technical support for your non-enterprise project? Chat with thousands of engineers within our growing Community on Discord