Explanation for different GraphQL directives

Question

I want to know about these different GraphQL directives. I tried to find online but didn't got explanation where all these directives works. Please explain about these different types of directive.

enum __DirectiveLocation {
    QUERY,
    MUTATION,
    SUBSCRIPTION,
    FIELD,
    FRAGMENT_DEFINITION,
    FRAGMENT_SPREAD,
    INLINE_FRAGMENT,
    SCHEMA,
    SCALAR,
    OBJECT,
    FIELD_DEFINITION,
    ARGUMENT_DEFINITION,
    INTERFACE,
    UNION,
    ENUM,
    ENUM_VALUE,
    INPUT_OBJECT,
    INPUT_FIELD_DEFINITION
}

user_6024220 · Answer

GraphQL directives can be used in any GraphQL document -- that includes both operations (like queries and mutation) as well as type definitions used to define a particular schema. A directive must specify one or more locations. These locations are split into two groups.

An ExecutableDirectiveLocation is for executable documents (i.e. ones that include operations that can be executed). This includes:

QUERY
MUTATION
SUBSCRIPTION
FIELD
FRAGMENT_DEFINITION
FRAGMENT_SPREAD
INLINE_FRAGMENT

A locations inside type system definitions (i.e type definitions used to create a schema) is called a TypeSystemDirectiveLocation and includes:

SCHEMA
SCALAR
OBJECT
FIELD_DEFINITION
ARGUMENT_DEFINITION
INTERFACE
UNION
ENUM
ENUM_VALUE
INPUT_OBJECT
INPUT_FIELD_DEFINITION

GraphQL documents may be represented as Abstract Syntax Tree (AST) objects consisting of AST Nodes. Each of the locations above matches an ASTNode of the same name.

Directives that utilize one or more TypeSystemDirectiveLocations are called schema directives. Libraries like Apollo Server allow us to define logic for schema directives that can be used to transform the schema element the directive is attached to. For example, with Apollo Server, we extend the SchemaDirectiveVisitor class, which has a method for each possible location -- the method is called when the schema is generated to determine how to change the targeted element in the schema.

Directives that use ExecutableDirectiveLocations are called client directives. Even though these are part of the spec, only two standard client directives exist -- @skip and @include. It's possible to define additional, custom client directives, but there's not currently a good way of implementing them on the server (at least not in the Node.js ecosystem).

Here's an example of usage of each directive location:

schema @SCHEMA {
  query: Query
}

scalar DateTime @SCALAR

type SomeType @OBJECT {
  someField(someArg: Int! @ARGUMENT_DEFINITION): String @FIELD_DEFINITION 
}

interface SomeInterface @INTERFACE {
  someField: String
}

union SomeUnion @UNION = SomeType | SomeOtherType

enum SomeEnum @ENUM {
  someEnumValue @ENUM_VALUE
}

input SomeInputType @INPUT_OBJECT {
  someInputField: String @INPUT_FIELD_DEFINITION 
}

And for executable documents:

query MyQuery @QUERY {
  someField @FIELD
  someOtherField {
    ...MyFragment @FRAGMENT_SPREAD
    ... on SomeType @INLINE_FRAGMENT {
      aDifferentField
    }
  }
}

fragment MyFragment @FRAGMENT_DEFINITION {
  yetAnotherField
}

mutation MyMutation @MUTATION {
  doSomething
}

subscription MySubscription @SUBSCRIPTION {
  somethingHappened
}

Explanation for different GraphQL directives

1 Answers