directus/docs/reference/api/query.md

pageClass

pageClass
page-reference

Global Query Parameters

Most operations within Directus can be manipulated with the following parameters:

• Fields
• Filter
• Search
• Sort
• Limit
• Offset / Page
• Deep
• Metadata
  • Total Count
  • Filter Count

---

Fields

Choose the fields that are returned in the current dataset. This parameter supports dot notation to request nested relational fields. You can also use a wildcard (*) to include all fields at a specific depth.

Examples

Get all top-level fields
*

Get all top-level fields and all second-level relational fields
*.*

::: warning Nested Wildcard

While you can theoretically keep nesting wildcards to your heart's content, it's not recommend for production use. Nested wildcards can result in degraded performance, and circular parent-child-parent structures.

:::

Get all top-level fields and second-level relational fields within images
*,images.*

Get only the first_name and last_name fields
first_name,last_name

Get all top-level and second-level relational fields, and third-level fields within images.thumbnails
*.*,images.thumbnails.*

Many-To-Any (Union Types)

Seeing that Many-to-Any (m2a) fields have nested data from multiple collections, it's not always safe / wanted to fetch the same field from every related collection. In m2a fields, you can use the following syntax to specify what fields to fetch from which related nested collection type:
?fields=<m2a-field>:<collection-scope>.<field>.

Lets say we have a collection pages with a many-to-any field called sections that points to headings, paragraphs, and videos. We only want to fetch title and level from headings, body from paragraphs and source from videos. We can achieve that by using:

sections.item:headings.title
sections.item:headings.level
sections.item:paragraphs.body
sections.item:videos.body

In GraphQL, this can be achieved using Union Types.

REST API

?fields=title,body,featured_image.*

// or

?fields[]=title
&fields[]=body
&fields[]=featured_image.*

GraphQL

n/a

---

Filter

Used to search items in a collection that matches the filter's conditions. The filter param follows the Filter Rules spec, which includes additional information on logical operators (AND/OR), nested relational filtering, and dynamic variables.

Examples

Retrieve all items where first_name equals "Rijk"

{
	"first_name": {
		"_eq": "Rijk"
	}
}

Retrieve all items in one of the following categories: "vegetables", "fruit"

{
	"categories": {
		"_in": ["vegetables", "fruit"]
	}
}

Retrieve all items where the author's "vip" flag is true

{
	"author": {
		"vip": {
			"_eq": true
		}
	}
}

::: tip Nested Filters

The above example will filter the top level items based on a condition in the related item. If you're looking to filter the related items themselves, take a look at the deep parameter!

:::

REST API

?filter[first_name][_eq]=Rijk

// or

?filter={ "first_name": { "_eq": "Rijk" }}

GraphQL

query {
	items {
		users(filter: { first_name: { _eq: "Rijk" } }) {
			id
		}
	}
}

---

Search

The search parameter allows you to perform a search on all string and text type fields within a collection. It's an easy way to search for an item without creating complex field filters – though it is far less optimized. It only searches the root item's fields, related item fields are not included.

Example

Find all items that mention Directus
Directus

REST API

?search=Directus

GraphQL

query {
	items {
		articles(search: "Directus") {
			id
		}
	}
}

---

Sort

What field(s) to sort by. Sorting defaults to ascending, but a minus sign (-) can be used to reverse this to descending order. Fields are prioritized by the order in the parameter.

Examples

Sort by creation date descending
-date_created

Sort by a "sort" field, followed by publish date descending
sort, -publish_date

REST API

?sort=sort,-date_created

// or

?sort[]=sort
&sort[]=-date_created

GraphQL

query {
	items {
		articles(sort: ["sort", "-date_created"]) {
			id
		}
	}
}

---

Limit

Set the maximum number of items that will be returned. The default limit is set to 100.

Examples

Get the first 200 items
200

Get all items
-1

::: warning All Items

Depending on the size of your collection, fetching unlimited data may result in degraded performance or timeouts, use with caution.

:::

REST API

?limit=200

GraphQL

query {
	items {
		articles(limit: 200) {
			id
		}
	}
}

---

Offset

Skip the first n items in the response. Can be used for pagination.

Examples

Get items 100—200
100

REST API

?offset=100

GraphQL

query {
	items {
		articles(offset: 100) {
			id
		}
	}
}

---

Page

An alternative to offset. Page is a way to set offset under the hood by calculating limit * page. Page is 1-indexed.

Examples

Get items 1-100
1

Get items 101-200
2

REST API

?page=2

GraphQL

query {
	items {
		articles(page: 2) {
			id
		}
	}
}

---

Deep

Deep allows you to set any of the other query parameters on a nested relational dataset.

Examples

Limit the nested related articles to 3

{
	"related_articles": {
		"limit": 3
	}
}

Fetch only the en-US translations

{
	"translations": {
		"filter": {
			"languages_code": {
				"_eq": "en-US"
			}
		}
	}
}

REST API

?deep[translations][filter][languages_code][_eq]=en-US

// or

?deep={ "translations": { "filter": { "languages_code": { "_eq": "en-US" }}}}

GraphQL

n/a

---

Metadata

Metadata allows you to retrieve some additional information about the items in the collection you're fetching. * can be used as a wildcard to retrieve all metadata.

Total Count

Returns the total item count of the collection you're querying.

Filter Count

Returns the item count of the collection you're querying, taking the current filter/search parameters into account.

REST API

?meta=total_count

?meta=filter_count

?meta=*

GraphQL

n/a

---