Filter Rules

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

¹ Compared value is not strictly typed for numeric values, allowing comparisons between numbers and their string representations.
² 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.

{
  "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.

{
  "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.

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

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

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

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

Dynamic Variables

{
  "owner": {
    "_eq": "$CURRENT_USER"
  }
}

{
  "datetime": {
    "_lte": "$NOW"
  }
}

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

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

Functions Parameters

{
  _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.

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