GraphQL Directives

Abhi Aiyer
May 24, 2016 · 2 min read

GraphQL queries are a powerful way to declare data in your application.

query myAwesomeQuery($keyword: String) {

After getting some experience writing these queries you’ll want to start doing more advanced things: inclusion/exclusion of fields, schema decorators, deferring fields etc.

Today we are going to talk about Directives. Directives provide a way describe additional options to the GraphQL executor. Essentially a directive allows the GraphQL to change the result of our queries based on criteria we provide. Today, the GraphQL spec defines two standard directives: @skip and @include.


The skip directive, when used on fields or fragments, allows us to exclude fields based on some condition.

query myAwesomeQuery($isAwesome: Boolean) {
awesomeField @skip(if: $isAwesome)

This example will return awesomeField only if $isAwesome is false.


The include directive, allows us to include fields based on some condition.

query myAwesomeQuery($isAwesome: Boolean) {
awesomeField @include(if: $isAwesome)

This example will return awesomeField only if $isAwesome is true.

Pretty neat right?

Let’s see what’s inside these directives

So before we get into it, directives aren’t really something GraphQL authors want you to create. Check out this github discussion: here.

We’ve determined that user-supplied custom directives is a non-goal for graphql-js at this time. — Lee Byron

If you’re interested in seeing a custom directive built, checkout this great blog post by Clay Allsopp here.

Let’s take a look how @skip is implemented. The root of a GraphQL directive is a GraphQLDirective class. Essentially this class is instantiated with the appropriate metadata.

Okay we have this directive, now how does it get used? GraphQL, graphql-js to be exact, employs a function called shouldIncudeNode. This function determines if a field should be included based on either the @include and @skip directives.

Note. @skip always has higher precedence than @include.

In GraphQL, a selectionSet is the set of information we are trying to resolve from our server. First, the GraphQL parses the string and turns it into an abstract syntax tree. Then after passing Validation, the selectionSet is executed and this is where our shouldIncudeNode function is called.

If you want to see how this is implemented check it out here!

Also, if you want to see how GraphQL queries work from query to execution check this blog from Jonas Helfer here.


GraphQL is super cool. At a glance all these concepts seem super new and I’m sure JavaScript developers are already feeling this as fatigue! But really, all you need to do is take a deep breath, dive into source code, and you’ll see that GraphQL is a powerful tool that is easy to use. If it was complex, it wouldn’t be such a good developer experience right?

Also, if you wanna jumpstart your usage of GraphQL today. Checkout the Apollo Stack. If you’re using REST APIs and hating your life, checkout how our client interface works here.


Open GraphQL

Anything & Everything GraphQL

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store