Operation Directives

Operation Directives provide a way to dynamically change the structure and shape of our queries using variables. An example from the GraphQL website:

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

Now if you set withFriends to true in the variables passed with the query POST you'll get the friends result. If you set it to false you will not. Thus dynamically changing the shape of your query.

Built-In Directives

The GraphQL spec defines 2 directives that are supported out of the box in EntityGraphQL.

• @include(if: Boolean) - Only include this field in the result if the argument is true.
• @skip(if: Boolean) - Skip this field if the argument is true.

Using a non-repeatable directive more than once at a single location (e.g. @skip(...) @skip(...)) is a validation error per the GraphQL spec. All built-in directives are non-repeatable.

Custom Directives

See the IncludeDirective implementation to see how you could implement a custom directive with IDirectiveProcessor. You can add your directive to the schema with the following

// Example only, you don't need to actually add Include or Skip directives
schema.AddDirective(new IncludeDirective());

A custom IDirectiveProcessor can override the IsRepeatable property (defaults to false) to allow the directive to be used multiple times at one location. Directives are exposed in introspection including isRepeatable.

These directives work on the internal representation of the query fields (see BaseGraphQLField.Directives) — they operate on the query graph before execution, not the data result.