Filter Rules | Directus Docs

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

Operator	Description
`_eq`	Equals
`_neq`	Doesn't equal
`_lt`	Less than
`_lte`	Less than or equal to
`_gt`	Greater than
`_gte`	Greater than or equal to
`_in`	Is one of
`_nin`	Is not one of
`_null`	Is `null`
`_nnull`	Isn't `null`
`_contains`	Contains
`_icontains`	Contains (case-insensitive)
`_ncontains`	Doesn't contain
`_starts_with`	Starts with
`_istarts_with`	Starts with (case-insensitive)
`_nstarts_with`	Doesn't start with
`_nistarts_with`	Doesn't start with (case-insensitive)
`_ends_with`	Ends with
`_iends_with`	Ends with (case-insensitive)
`_nends_with`	Doesn't end with
`_niends_with`	Doesn't end with (case-insensitive)
`_between`	Is between two values (inclusive)
`_nbetween`	Is not between two values (inclusive)
`_empty`	Is empty (`null` or falsy)
`_nempty`	Isn't empty (`null` or falsy)
`_intersects` ¹	Intersects a point
`_nintersects` ¹	Doesn't intersect a point
`_intersects_bbox` ¹	Intersects a bounding box
`_nintersects_bbox` ¹	Doesn't intersect a bounding box
`_regex` ²	Regular expression (escape backslashes)
`_some` ³	At least one related value is true
`_none` ³	No related values are true

¹ Only available on geometry fields.
² Only available in validation permissions.
³ 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 specify related values by nesting field names. For example, if you have a relational Many to One author field, and want to specify a filter on the author's name field:

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

When applying filters to a One to Many field, Directus will default to a 'some' search.

Example
This filter checks all related category names and will check is at least one value is equal to 'Recipe':

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

This behavior can be overridden by using the explicit _some and _none operators.

Example

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

Dynamic Variables

Variable	Description
`$CURRENT_USER`	The primary key of the currently authenticated user.
`$CURRENT_ROLE`	The primary key of the role for the currently authenticated user
`$NOW`	The 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"
  }
}

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).

Function	Description
`year`	Extract the year from a datetime/date/timestamp field
`month`	Extract the month from a datetime/date/timestamp field
`week`	Extract the week from a datetime/date/timestamp field
`day`	Extract the day from a datetime/date/timestamp field
`weekday`	Extract the weekday from a datetime/date/timestamp field
`hour`	Extract the hour from a datetime/date/timestamp field
`minute`	Extract the minute from a datetime/date/timestamp field
`second`	Extract the second from a datetime/date/timestamp field
`count`	Extract the number of items from a JSON array or relational field

Example

{
  _and: [
    {
      "year(published_date)": {
        _eq: 1968,
      },
    },
    {
      "month(published_date)": {
        _eq: 4,
      },
    },
  ],
},

Authentication

Discover how to authenticate Directus Connect requests using authorization headers, session cookies, or query parameters.

Query Parameters

Learn about Directus query parameters - fields, filter, search, sort, limit, offset, page, aggregate, groupBy, deep, alias, and export. Understand how to customize your API requests and retrieve specific data from your collections.