Connect

Filter Rules

Learn about filter rules in Directus - available operators, filter syntax, relational fields, dynamic variables, logical operators, and functions parameters. Understand how to build complex filters for permissions, validations, and automations.

Filters are used in permissions, validations, and automations, as well as throughout the APIs and in extensions. All filters use standard syntax and operators which are described on this page.

Available Operators

OperatorDescription
_eqEquals
_neqDoesn't equal
_ltLess than
_lteLess than or equal to
_gtGreater than
_gteGreater than or equal to
_inIs one of
_ninIs not one of
_nullIs null
_nnullIsn't null
_containsContains
_icontainsContains (case-insensitive)
_ncontainsDoesn't contain
_starts_withStarts with
_istarts_withStarts with (case-insensitive)
_nstarts_withDoesn't start with
_nistarts_withDoesn't start with (case-insensitive)
_ends_withEnds with
_iends_withEnds with (case-insensitive)
_nends_withDoesn't end with
_niends_withDoesn't end with (case-insensitive)
_betweenIs between two values (inclusive)
_nbetweenIs not between two values (inclusive)
_emptyIs empty (null or falsy)
_nemptyIsn't empty (null or falsy)
_intersects 1Intersects a point
_nintersects 1Doesn't intersect a point
_intersects_bbox 1Intersects a bounding box
_nintersects_bbox 1Doesn't intersect a bounding box
_regex 2Regular expression (escape backslashes)
_some 3At least one related value is true
_none 3No related values are true

1 Only available on geometry fields.
2 Only available in validation permissions.
3 Only available on One to Many relationship fields.

Filter Syntax

{
  "field": {
    "operator": "value"
  }
}

The field can exist on the current collection or a relational collection.

The operator must be any valid filter operator such as 'equals' or 'contains'.

The value can be any fixed static value or one of the provided dynamic variables.

Example

This filter checks the title field contains the case-sensitive substring 'Directus':

{
  "title": {
    "_contains": "Directus"
  }
}

Relational Fields

You can filter items based on related data by nesting field names in your query. This allows you to query items not just by their own fields, but also by values in related collections.

Many-to-One

You can filter items with Many-to-One relations by specifying values of their respective fields.

Example

For example, if you have an articles collection with a relational Many-to-One author field, you can filter articles based on the author's details—such as their name.

{
  "author": {
      "name": {
        "_eq": "Rijk van Zanten"
      }
  }
}

Many-to-Many

When using Many-to-Many relationships, a junction table will be created and the filter applies to the junction table itself. For example, if you have a books collection, with a Many-to-Many relationship to authors of each book, the junction collection will probably be named books_authors and have 3 fields : id, books_id and authors_id. To filter specific books depending on their authors you must go through the junction table and the authors_id field :

{
  "authors": {
    "authors_id": {
      "name": {
        "_eq": "Rijk van Zanten"
      }
    }
  }
}

_some vs _none in One-to-Many and Many-to-Many

The _some and _none filter operators can be used for filtering One-to-Many and Many-to-Many relational fields in API queries. They allow you to filter items based on conditions applied to their related collections.

The _some operator matches items where at least one related item meets the condition. By default, Directus will apply the _some operator when querying One-to-Many and Many-to-Many relational queries.

Example

This filter matches all items where at least one related category has the name "Recipe":

{
  "categories": {
    "_some": {
      "name": {
        "_eq": "Recipe"
      }
    }
  }
}

In the above, categories is the relational field in the collection. _some checks if at least one related category has the name "Recipe". If an item has one or more categories named "Recipe", it will be included in the result.

Since _some is applied by default, the below is equivalent:

{
  "categories": {
    "name": {
      "_eq": "Recipe"
    }
  }
}

The _none operator matches items where none of the related items meet the condition.

Example

This filter matches all items where none of the categories has the name "Recipe":

{
  "categories": {
    "_none": {
      "name": {
        "_eq": "Recipe"
      }
    }
  }
}

In the above, categories is the relational field in the collection. _none checks if no related category has the name "Recipe". If an item has no categories named "Recipe", it will be included in the result.

Dynamic Variables

VariableDescription
$CURRENT_USERThe primary key of the currently authenticated user.
$CURRENT_ROLEThe primary key of the role for the currently authenticated user
$NOWThe current timestamp
$NOW(<adjustment>)The current timestamp plus/minus a given distance, for example $NOW(-1 year), $NOW(+2 hours)
Examples
{
  "owner": {
    "_eq": "$CURRENT_USER"
  }
}
{
  "datetime": {
    "_lte": "$NOW"
  }
}
Example

Nested user and role variables in permissions When configuring permissions, $CURRENT_USER and $CURRENT_ROLE allow you to specify any related field, such as $CURRENT_ROLE.name or $CURRENT_USER.avatar.filesize.

Logical Operators

You can group multiple rules using the _and or _or logical operators. Each logical operator holds an array of filter rules. Logical operators can be nested directly inside of each other, but not inside of other filter rules.

{
  "_and": [
    {
      "field": {
        "operator": "value"
      }
    },
    {
      "field": {
        "operator": "value"
      }
    }
  ]
}
Example
{
  "_or": [
    {
      "_and": [
        {
          "user_created": {
            "_eq": "$CURRENT_USER"
          }
        },
        {
          "status": {
            "_in": ["published", "draft"]
          }
        }
      ]
    },
    {
      "_and": [
        {
          "user_created": {
            "_neq": "$CURRENT_USER"
          }
        },
        {
          "status": {
            "_in": ["published"]
          }
        }
      ]
    }
  ]
}

Functions Parameters

Functions accept a field and return a modified value. Functions can be used in any query parameter you'd normally supply a field key, including fields, aggregation, and filters.

The syntax for using a function is function(field).

FunctionDescription
yearExtract the year from a datetime/date/timestamp field
monthExtract the month from a datetime/date/timestamp field
weekExtract the week from a datetime/date/timestamp field
dayExtract the day from a datetime/date/timestamp field
weekdayExtract the weekday from a datetime/date/timestamp field
hourExtract the hour from a datetime/date/timestamp field
minuteExtract the minute from a datetime/date/timestamp field
secondExtract the second from a datetime/date/timestamp field
countExtract the number of items from a JSON array or relational field
Example
{
  _and: [
    {
      "year(published_date)": {
        _eq: 1968,
      },
    },
    {
      "month(published_date)": {
        _eq: 4,
      },
    },
  ],
},

Follow Syntax

Filters allow you to query relations from collections directly.

For cases where you wish to query an indirect relation, such as countries to which cities have an M2O relation, you can use the $FOLLOW(target-collection, relation-field) syntax.

This is useful when there is a relation from the target collection to the current collection, but no relation field has been configured in the current collection to the target collection.

Example

There exists both a cities and a countries collection. cities have an M2O relationship with countries via the country_id field. You can query countries via the fields of its related cities using the following:

{
  "filter": {
    "name": "Germany",
    "$FOLLOW(cities, country_id)": {
        "name": "Berlin"
    }
  }
}