How to filter the Directus API

The Directus API has a powerful filtering system built into it's core. You can easily filter your results across your available fields. Filtering your data is essential for optimizing your connections. Especially when dealing with a lot of data. In this article I will cover the use of filters in GraphQL and REST API.

To use filters in the Directus API, simply add the filter parameter and use the Directus Documentation to formulate the desired filter from your available fields.

Filters in GraphQL

Directus combined with GraphQL is very powerful. The filter parameter can be added to a query to change what data is returned. Below I have filtered the results using a relational table on the author's first name.

query {
    articles(
        filter: { author: first_name: { _eq: "Robert" } } }
    ) {
        id
        title
        author {
            first_name
        }
    }
}

What we expect to see is all articles authored by Robert in order of when they where created.

I recommend reading through the Directus documentation for all the possiblities of the filters, such as _eq, _neq, _in, _nin, _between ...

The GraphQL must be wrapped in JSON so the CURL command looks something like this.

curl -H "Authorization: Bearer your-bearer-token" -X POST -d '{"query": "query { articles(filter: { author: first_name: { _eq: "Robert" } } }) { id title author { first_name }}}"}' https://directus.example.com/graphql

To include a second filter, you need to expand the JSON array to inlcude _and or _or parameters.

query {
    articles(
        filter: {
            _and: [
                { author: first_name: { _eq: "Robert" } },
                { title: { _contains: "NodeJS" }
            ]
        }
    ) {
        id
        title
        author {
            first_name
        }
    }
}

This will return all articles from Robert that contains NodeJS in the title.

Filters in REST API

Adding the filter parameter works quite differently for REST APIs, the main difference is the use of square brackets [ ] for each dimension of the filter array.

To replicate the same example as above, here is the request URL. Note the format of the filter parameter.

https://directus.example.com/items/articles?fields=id,title,author.first_name&filter[author][first_name][_eq]=Robert

Observation: If you have any spaces in your filter values, make sure they are replaced by a +, also known as url encoded.

Again, what we expect to see is all articles authored by Robert.

The query in CURL is quite simple since all the parameters are in the URL.

curl -H "Authorization: Bearer your-bearer-token" https://directus.example.com/items/articles?fields=id,title,author.first_name&filter[author][first_name][_eq]=Robert

To include a second filter, simply add another filter parameter to the URL.

https://directus.example.com/items/articles?fields=id,title,author.first_name&filter[author][first_name][_eq]=Robert&filter[title][_contains]=NodeJS

This will return all articles from Robert that contains NodeJS in the title.

Documentation

Use the Directus documentation to see the full list of possibilities.

Filter Rules | Directus Docs

Directus 9. An Instant App & API for your SQL Database.

Directus Docs

Conclusion

Filters are essential for any project, especially when dealing with massive data sources. It can really reduce the load and bandwidth of your server.