Filter Rules

Permissions, validation, and the API's filter parameter all rely on a specific JSON structure to define their rules. This page describes the syntax for creating flat, relational, or complex filter rules.

toc

Syntax

Field — Any valid root field, relational field, or logical operator
Operator — Any valid API operator prefaced with an underscore
Value — Any valid static value, or dynamic variable

{
	<field>: {
		<operator>: <value>
	}
}

Examples

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

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

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

Filter Operators

Operator	Description
`_eq`	Equal to
`_neq`	Not equal to
`_lt`	Less than
`_lte`	Less than or equal to
`_gt`	Greater than
`_gte`	Greater than or equal to
`_in`	Exists in one of the values
`_nin`	Not in one of the values
`_null`	It is null
`_nnull`	It is not null
`_contains`	Contains the substring
`_ncontains`	Doesn't contain the substring
`_starts_with`	Contains the substring
`_nstarts_with`	Doesn't contain the substring
`_ends_with`	Contains the substring
`_nends_with`	Doesn't contain the substring
`_between`	The value is between two values
`_nbetween`	The value is not between two values
`_empty`	The value is empty (null or falsy)
`_nempty`	The value is not empty (null or falsy)

The following operators are only available in validation permissions:

Operator	Description
`_submitted`	Field has to be submitted
`_regex` ^[1]	Field has to match regex

^[1] JavaScript "flavor" regex. Make sure to escape backslashes.

Relational

You can target related values by nesting field names. For example, if you have a relational Many-to-One author field, you can set a rule for the author.name field using the following syntax.

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

Logical Operators

You can nest or group multiple rules using the _and or _or logical operators. Each operator holds an array of rules, allowing for more complex filtering.

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

Dynamic Variables

In addition to static values, you can also filter against dynamic values using the following variables.

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

3.8 KiB Raw Blame History