Directives

Directives are system-defined keywords that modify execution. All GraphQL systems have at least two directives, @skip and @include. For example:

query ProfileView($renderingDetailedProfile: Boolean!){
  viewer {
    handle
    # These fields will be included only if the check passes:
    ... @include(if: $renderingDetailedProfile) {
      location
      homepageUrl
    }
  }
}

Here’s how the two built-in directives work:

• @skip(if: ...) skips the selection if the if: ... value is truthy (GraphQL::Schema::Directive::Skip)
• @include(if: ...) includes the selection if the if: ... value is truthy (GraphQL::Schema::Directive::Include)

GraphQL-Ruby also supports custom directives for use with the interpreter runtime.

Custom Directives

Custom directives extend GraphQL::Schema::Directive:

# app/graphql/directives/my_directive.rb
class Directives::MyDirective < GraphQL::Schema::Directive
  description "A nice runtime customization"
end

Then, they’re hooked up to the schema using directive(...):

class MySchema < GraphQL::Schema
  # Custom directives are only supported by the Interpreter runtime
  use GraphQL::Execution::Interpreter
  # Attach the custom directive to the schema
  directive(Directives::MyDirective)
end

GraphQL::Schema::Directive::Feature and GraphQL::Schema::Directive::Transform are included in the library as examples.

Arguments

Like fields, directives may have arguments :

argument :if, Boolean, required: true,
  description: "Skips the selection if this condition is true"

Runtime hooks

Directive classes may implement the following class methods to interact with the runtime:

• def self.include?(obj, args, ctx): If this hook returns false, the nodes flagged by this directive will be skipped at runtime.
• def self.resolve(obj, args, ctx): Wraps the resolution of flagged nodes. Resolution is passed as a block, so yield will continue resolution. The return value of this method will be treated as the return value of the flagged field.

Looking for a runtime hook that isn’t listed here? open an issue to start the conversation!

Directive object lifecycle

Currently, Directive classes are never initialized. A later version of GraphQL may initialize these objects for runtime application.