graphql-ruby Documentation

Technical Documentation: rmosolgo/graphql-ruby

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`readme.md`) Copy Section

graphql

A Ruby implementation of GraphQL.

• Website
• API Documentation
• Newsletter

Installation Copy Chapter

Install from RubyGems by adding it to your Gemfile, then bundling.

# Gemfile
gem 'graphql'

$ bundle install

Getting Started Copy Chapter

$ rails generate graphql:install

After this, you may need to run bundle install again, as by default graphiql-rails is added on installation.

Or, see "Getting Started".

Upgrade Copy Chapter

I also sell GraphQL::Pro which provides several features on top of the GraphQL runtime, including:

• Persisted queries
• API versioning
• Streaming payloads
• Server-side caching
• Rate limiters
• Subscriptions backends for Pusher and Ably
• Authorization plugins for Pundit and CanCan

Besides that, Pro customers get email support and an opportunity to support graphql-ruby's development!

Goals Copy Chapter

• Implement the GraphQL spec & support a Relay front end
• Provide idiomatic, plain-Ruby API with similarities to reference implementation where possible
• Support Ruby on Rails and Relay

Getting Involved Copy Chapter

• Say hi & ask questions in the #graphql-ruby channel on Discord.
• Report bugs by posting a description, full stack trace, and all relevant code in a GitHub issue.
• Start hacking with the Development guide.

Overview (`javascript_client/readme.md`) Copy Section

Find the graphql-ruby-client docs on the GraphQL-Ruby website.

License Copy Chapter

graphql-ruby-client is available under the LGPLv3 license;
graphql-pro customers are granted a special commercial license.

Development Copy Chapter

• With GraphQL-Ruby:
  • Install the dependencies with rake js:install
  • Run the tests with rake js:test
• Stand-alone:
  • Install dependencies yarn install
  • Run the tests yarn run test
• Run the TypeScript compiler: yarn tsc -w
• Install for local development with npm link .

Guides Authorization Overview (`guides/authorization/overview.md`) Copy Section

Overview

Here's a conceptual approach to GraphQL authorization, followed by an introduction to the built-in authorization framework. Each part of the framework is described in detail in its own guide.

Authorization: GraphQL vs REST Copy Chapter

In a REST API, the common authorization pattern is fairly simple. Before performing the requested action, the server asserts that the current client has the required permissions for that action. For example:

class PostsController < ApiController
  def create
    # First, check the client's permission level:
    if current_user.can?(:create_posts)
      # If the user is permitted, then perform the action:
      post = Post.create(params)
      render json: post
    else
      # Otherwise, return an error:
      render nothing: true, status: 403
    end
  end
end

However, this request-by-request mindset doesn't map well to GraphQL because there's only one controller and the requests that come to it may be very different. To illustrate the problem:

class GraphqlController < ApplicationController
  def execute
    # What permission is required for `query_str`?
    # It depends on the string! So, you can't generalize at this level.
    if current_user.can?(:"???")
      MySchema.execute(query_str, context: ctx, variables: variables)
    end
  end
end

So, what new mindset will work with a GraphQL API?

For mutations, remember that each mutation is like an API request in itself. For example, Posts#create above would map to the createPost(...) mutation in GraphQL. So, each mutation should be authorized in its own right.

For queries, you can think of each individual object like a GET request to a REST API. So, each object should be authorized for reading in its own right.

By applying this mindset, each part of the GraphQL query will be properly authorized before it is executed. Also, since the different units of code are each authorized on their own, you can be sure that each incoming query will be properly authorized, even if it's a brand new query that the server has never seen before.

What About Authentication? Copy Chapter

As a reminder:

• Authentication is the process of determining what user is making the current request, for example, accepting a username and password, or finding a User in the database from session[:current_user_id].
• Authorization is the process of verifying that the current user has permission to do something (or see something), for example, checking admin? status or looking up permission groups from the database.

In general, authentication is not addressed in GraphQL at all. Instead, your controller should get the current user based on the HTTP request (eg, an HTTP header or a cookie) and provide that information to the GraphQL query. For example:

class GraphqlController < ApplicationController
  def execute
    # Somehow get the current `User` from this HTTP request.
    current_user = get_logged_in_user(request)
    # Provide the current user in `context` for use during the query
    context = { current_user: current_user }
    MySchema.execute(query_str, context: context, ...)
  end
end

After your HTTP handler has loaded the current user, you can access it via context[:current_user] in your GraphQL code.

Authorization in Your Business Logic Copy Chapter

Before introducing GraphQL-specific authorization, consider the advantages of application-level authorization. (See the GraphQL.org post on the same topic.) For example, here's authorization mixed into the GraphQL API layer:

field :posts, [Types::Post], null: false

def posts
  # Perform an auth check in the GraphQL field code:
  if context[:current_user].admin?
    Post.all
  else
    Post.published
  end
end

The downside of this is that, when Types::Post is queried in other contexts, the same authorization check may not be applied. Additionally, since the authorization code is coupled with the GraphQL API, the only way to test it is via GraphQL queries, which adds some complexity to tests.

Alternatively, you could move the authorization to your business logic, the Post class:

class Post < ActiveRecord::Base
  # Return the list of posts which `user` may see
  def self.posts_for(user)
    if user.admin?
      self.all
    else
      self.published
    end
  end
end

Then, use this application method in your GraphQL code:

field :posts, [Types::Post], null: false

def posts
  # Fetch the posts this user can see:
  Post.posts_for(context[:current_user])
end

In this case, Post.posts_for(user) could be tested independently from GraphQL. Then, you have less to worry about in your GraphQL tests. As a bonus, you can use Post.posts_for(user) in other parts of the app, too, such as the web UI or REST API.

GraphQL-Ruby's Authorization Framework Copy Chapter

Despite the advantages of authorization at the application layer, as described above, there might be some reasons to authorize in the API layer:

• Have an extra assurance that your API layer is secure
• Authorize the API request before running it (see "visibility" below)
• Integrate with code that doesn't have authorization built-in

To accomplish these, you can use GraphQL-Ruby's authorization framework. The framework has three levels, each of which is described in its own guide:

• Visibility hides parts of the GraphQL schema from users who don't have full permission.
• Authorization checks application objects during execution to be sure the user has permission to access them.

Also, GraphQL::Pro has integrations for CanCan and Pundit.

Guides Changesets Overview (`guides/changesets/overview.md`) Copy Section

API Versioning for GraphQL-Ruby

Out-of-the-box, GraphQL is versionless by design. GraphQL's openness to extension paves the way for continuously expanding and improving an API. You can always add new fields, new arguments, and new types to implement new features and customize existing behavior.

However, sometimes a business case may call for a different versioning scheme. GraphQL-Enterprise's "Changesets" enable schemas to release any change -- even breaking changes -- to clients, depending on what version of the schema they're using. With Changesets, you can redefine existing fields, define new types using old names, add or remove enum values -- anything, really -- while maintaining compatibility for existing clients.

Why Changesets? Copy Chapter

Changesets are a complementary evolution technique to continuous additions. In general, additive changes (new fields, new arguments, new types) are best added right to the existing schema. But if you need to remove something from the schema or redefine existing parts of the schema in non-backwards-compatible ways, Changesets provide a handy way of doing so.

For example, if you add a values to an Enum, you can just add it to the existing schema:

class Types::RecipeTag < Types::BaseEnum
    value "LOW_FAT"
    value "LOW_CARB"
+   value "VEGAN"
+   value "KETO"
+   value "GRAPEFRUIT_DIET"
  end

However, if you want to change the schema in ways that would break previous queries, you can do that with a Changeset:

class Types::RecipeTag < Types::BaseEnum
  # Turns out this makes you sick:
  value "GRAPEFRUIT_DIET", removed_in: Changesets::RemoveLegacyDiets
end

Then, only clients requesting API versions before this changeset would be able to use GRAPEFRUIT_DIET; clients requesting newer versions could not send it as input and would not receive it in responses.

(Changesets also support additive changes, if you prefer to make them that way.)

Getting Started Copy Chapter

To start using Changesets, read on:

• Installing Changesets
• Writing Changesets
• Releasing Changesets

Guides Dataloader Overview (`guides/dataloader/overview.md`) Copy Section

Overview

GraphQL::Dataloader provides efficient, batched access to external services, backed by Ruby's Fiber concurrency primitive. It has a per-query result cache and AsyncDataloader supports truly parallel execution out-of-the-box.

GraphQL::Dataloader is inspired by @bessey's proof-of-concept and shopify/graphql-batch.

Batch Loading Copy Chapter

GraphQL::Dataloader facilitates a two-stage approach to fetching data from external sources (like databases or APIs):

• First, GraphQL fields register their data requirements (eg, object IDs or query parameters)
• Then, after as many requirements have been gathered as possible, GraphQL::Dataloader initiates actual fetches to external services

That cycle is repeated during execution: data requirements are gathered until no further GraphQL fields can be executed, then GraphQL::Dataloader triggers external calls based on those requirements and GraphQL execution resumes.

Fibers Copy Chapter

GraphQL::Dataloader uses Ruby's Fiber, a lightweight concurrency primitive which supports application-level scheduling within a Thread. By using Fiber, GraphQL::Dataloader can pause GraphQL execution when data is requested, then resume execution after the data is fetched.

At a high level, GraphQL::Dataloader's usage of Fiber looks like this:

• GraphQL execution is run inside a Fiber.
• When that Fiber returns, if the Fiber was paused to wait for data, then GraphQL execution resumes with the next (sibling) GraphQL field inside a new Fiber.
• That cycle continues until no further sibling fields are available and all known Fibers are paused.
• GraphQL::Dataloader takes the first paused Fiber and resumes it, causing the GraphQL::Dataloader::Source to execute its #fetch(...) call. That Fiber continues execution as far as it can.
• Likewise, paused Fibers are resumed, causing GraphQL execution to continue, until all paused Fibers are evaluated completely.

Whenever GraphQL::Dataloader creates a new Fiber, it copies each pair from Thread.current[...] and reassigns them inside the new Fiber.

AsyncDataloader, built on top of the async gem, supports parallel I/O operations (like network and database communication) via Ruby's non-blocking Fiber.schedule API. Learn more →.

Getting Started Copy Chapter

To install GraphQL::Dataloader, add it to your schema with use ..., for example:

class MySchema < GraphQL::Schema
  # ...
  use GraphQL::Dataloader
end

Then, inside your schema, you can request batch-loaded objects by their lookup key with dataloader.with(...).load(...):

field :user, Types::User do
  argument :handle, String
end

def user(handle:)
  dataloader.with(Sources::UserByHandle).load(handle)
end

Or, load several objects by passing an array of lookup keys to .load_all(...):

field :is_following, Boolean, null: false do
  argument :follower_handle, String
  argument :followed_handle, String
end

def is_following(follower_handle:, followed_handle:)
  follower, followed = dataloader
    .with(Sources::UserByHandle)
    .load_all([follower_handle, followed_handle])

  followed && follower && follower.follows?(followed)
end

To prepare requests from several sources, use .request(...), then call .load after all requests are registered:

class AddToList < GraphQL::Schema::Mutation
  argument :handle, String
  argument :list, String, as: :list_name

  field :list, Types::UserList

  def resolve(handle:, list_name:)
    # first, register the requests:
    user_request = dataloader.with(Sources::UserByHandle).request(handle)
    list_request = dataloader.with(Sources::ListByName, context[:viewer]).request(list_name)
    # then, use `.load` to wait for the external call and return the object:
    user = user_request.load
    list = list_request.load
    # Now, all objects are ready.
    list.add_user!(user)
    { list: list }
  end
end

`loads:` and `object_from_id` Copy Section

dataloader is also available as context.dataloader, so you can use it to implement MySchema.object_from_id. For example:

class MySchema < GraphQL::Schema
  def self.object_from_id(id, ctx)
    model_class, database_id = IdDecoder.decode(id)
    ctx.dataloader.with(Sources::RecordById, model_class).load(database_id)
  end
end

Then, any arguments with loads: will use that method to fetch objects. For example:

class FollowUser < GraphQL::Schema::Mutation
  argument :follow_id, ID, loads: Types::User

  field :followed, Types::User

  def resolve(follow:)
    # `follow` was fetched using the Schema's `object_from_id` hook
    context[:viewer].follow!(follow)
    { followed: follow }
  end
end

Data Sources Copy Chapter

To implement batch-loading data sources, see the Sources guide.

Parallelism Copy Chapter

You can run I/O operations in parallel with GraphQL::Dataloader. There are two approaches:

• AsyncDataloader uses the async gem to automatically background I/O from Dataloader::Source#fetch calls. Read More
• You can manually call dataloader.yield after starting work in the background. Read More

Guides Defer Overview (`guides/defer/overview.md`) Copy Section

Overview

@defer is a directive for streaming GraphQL responses from the server to the client.

By streaming the response, the server can send the most critical (or most available) data first, following up with secondary data shortly afterward.

@defer was first described by Lee Byron at React Europe 2015 and got experimental support in Apollo in 2018.

@stream is like @defer, but it returns list items one at a time. Find details in the Stream guide.

Example Copy Chapter

GraphQL queries can be large and complex, requiring lots of computation or dependencies on slow external services.

In this example, the local server maintains an index of items ("decks"), but the item data ("cards") is actually hosted on a remote server. So, GraphQL queries must make remote calls in order to serve that data.

Without @defer, the whole query is blocked until the last field is done resolving:

But, we can add @defer to slow fields:

deck {
    slots {
      quantity
-     card
+     card @defer {
        name
        price
      }
    }
  }

Then, the response will stream to the client bit by bit, so the page can load progressively:

This way, clients get a snappy feel from the app even while data is still loading.

View the full demo at https://github.com/rmosolgo/graphql_defer_example.

Considerations Copy Chapter

• @defer adds some overhead to the response, so only apply it judiciously.
• @defer is single-threaded. @defered fields are still evaluated in sequence, but in a chunk-by-chunk way.

Next Steps Copy Chapter

Set up your server to support @defer or read about client usage of it.

Guides Errors Overview (`guides/errors/overview.md`) Copy Section

Errors in GraphQL

There are a lot of different kinds of errors in GraphQL! In this guide, we'll discuss some of the main categories and learn when they apply.

Validation Errors Copy Chapter

Because GraphQL is strongly typed, it performs validation of all queries before executing them. If an incoming query is invalid, it isn't executed. Instead, a response is sent back with "errors":

{
  "errors" => [ ... ]
}

Each error has a message, line, column and path.

The validation rules are part of the GraphQL specification and built into GraphQL-Ruby, so there's not really a way to customize this behavior, except to pass validate: false when executing a query, which skips validation altogether.

You can configure your schema to stop validating after a certain number of errors by setting Schema.validate_max_errors. Also, you can add a timeout to this step with Schema.validate_timeout.

Analysis Errors Copy Chapter

GraphQL-Ruby supports pre-execution analysis, which may return "errors" instead of running a query. You can find details in the Analysis guide.

GraphQL Invariants Copy Chapter

While GraphQL-Ruby is executing a query, some constraints must be satisfied. For example:

• Non-null fields may not return nil.
• Interface and union types must resolve objects to types that belong to that interface/union.

These constraints are part of the GraphQL specification, and when they are violated, it must be addressed somehow. Read more in Type Errors.

Top-level `"errors"` Copy Chapter

The GraphQL specification provides for a top-level "errors" key which may include information about errors during query execution. "errors" and "data" may both be present in the case of a partial success.

In your own schema, you can add to the "errors" key by raising GraphQL::ExecutionError (or subclasses of it) in your code. Read more in the Execution Errors guide.

Handled Errors Copy Chapter

A schema can be configured to handle certain errors during field execution with handlers that you give it, using rescue_from. Read more in the Error Handling guide.

Unhandled Errors (Crashes) Copy Chapter

When a raised error is not rescued, the GraphQL query crashes entirely and the surrounding code (like a Rails controller) must handle the exception.

For example, Rails will probably return a generic 500 page.

Errors as Data Copy Chapter

When you want end users (human beings) to read error messages, you can express errors in the schema, using normal GraphQL fields and types. In this approach, errors are strongly-typed data, queryable in the schema, like any other application data.

For more about this approach, see Mutation Errors

Guides Javascript Client Overview (`guides/javascript_client/overview.md`) Copy Section

Overview

There is a JavaScript client for GraphQL-Ruby, graphql-ruby-client.

You can install it from NPM or Yarn:

yarn add graphql-ruby-client
# Or:
npm install graphql-ruby-client

The source code is in the graphql-ruby repository.

See detailed guides for more info about its features:

• sync CLI for use with graphql-pro's persisted query backend
• Subscription support:
  • Apollo integration
  • Relay integration
  • urql integration
  • GraphiQL integration

Guides Limiters Overview (`guides/limiters/overview.md`) Copy Section

Rate Limiters for GraphQL

GraphQL::Enterprise includes rate limiters built especially for GraphQL.

For REST APIs, rate limiters often count requests and block clients when they exceed their limit over a certain period of time. However, this paradigm doesn't translate well to GraphQL because the cost of serving a request may vary dramatically depending on the GraphQL query contained in the request. Instead, GraphQL::Enterprise implements two other kinds of limiters:

• An active operation limiter which allows clients to run a certain number of operations at a time. For example, if the limit is five concurrent operations, and a client sends six requests simultaneously, then only five of those incoming operations will be executed; the sixth will be returned with an error and it may be retried when one of the five others finishes.
• A runtime limiter which limits the amount of processing time a client may consume during a given window. For example, a limit of 120 seconds per minute would allow two concurrent requests on average -- although in practice, it might be spiky: perhaps five concurrent, 20-second-long requests, followed by 40 seconds of no requests.

There's some overlap in these limiters; both of them constrain the amount of time a client may force the server to spend in handling requests. The active operation limiter puts an upper bound on how many processes a client may occupy while the runtime limiter puts a bound on total processing time (regardless of the number of concurrent operations at a given moment).

To get started, read on:

• Configure Redis for the limiters' backend
• Active Operation Limiter
• Runtime Limiter

Guides Object Cache Overview (`guides/object_cache/overview.md`) Copy Section

GraphQL ObjectCache

GraphQL::Enterprise::ObjectCache is an application-level cache for GraphQL-Ruby servers. It works by storing a cache fingerprint for each object in a query, then serving a cached response as long as those fingerprints don't change. The cache can also be customized with TTLs.

Why? Copy Chapter

ObjectCache can greatly reduce GraphQL response times by serving cached responses when the underlying data for a query hasn't changed.

Usually, a GraphQL query alternates between data fetching and calling application logic:

But with ObjectCache, it checks the cache first, returning a cached response if possible:

This reduces latency for clients and reduces the load on your database and application server.

How Copy Chapter

Before running a query, ObjectCache creates a fingerprint for the query using GraphQL::Query#fingerprint and Schema.context_fingerprint_for(ctx). Then, it checks the backend for a cached response which matches the fingerprint.

If a match is found, the ObjectCache fetches the objects previously visited by this query. Then, it compares the current fingerprint of each object ot the one in the cache and checks .authorized? for that object. If the fingerprints all match and all objects pass authorization checks, then the cached response returned. (Authorization checks can be disabled.)

If there is no cached response or if the fingerprints don't match, then the incoming query is re-evaluated. While it's executed, ObjectCache gathers the IDs and fingerprints of each object it encounters. When the query is done, the result and the new object fingerprints are written to the cache.

Setup Copy Chapter

To get started with the object cache:

• Prepare the schema
• Set up a Redis backend or Memcached backend
• Configure types and fields for caching
• Check out the runtime considerations

Guides Operation Store Overview (`guides/operation_store/overview.md`) Copy Section

Overview

GraphQL::Pro::OperationStore uses Rack and a storage backend (ActiveRecord or Redis) to maintain a normalized, deduplicated database of persisted queries for your GraphQL system.

In this guide, you'll find:

• Description of persisted queries
• The rationale behind them
• How OperationStore works, in brief

In other guides, you can read more about:

• Getting Started installing OperationStore in your app
• Workflow and usage for client apps
• Authentication for the sync API
• Server Management after your system is running

Also, you can find a demo app on GitHub.

What are Persisted Queries? Copy Chapter

Persisted queries are GraphQL queries (query, mutation, or subscription) that are saved on the server and invoked by clients by reference. In this arrangement, clients don't send GraphQL queries over the network. Instead, clients send:

• Client name, to identify the client who is making the request
• Query alias, to specify which stored operation to run
• Query variables, to provide values for the stored operation

Then, the server uses the identifier to fetch the full GraphQL document from the database.

Without persisted queries, clients send the whole document:

# Before, without persisted queries
query_string = "query GetUserDetails($userId: ID!) { ... }"

MyGraphQLEndpoint.post({
  query: query_string,
  operationName: "GetUserDetails",
  variables: { userId: "100" },
})

But with persisted queries, the full document isn't sent because the server already has a copy of it:

# After, with persisted queries:
MyGraphQLEndpoint.post({
  operationId: { "relay-app-v1/fc84dbba3623383fdc",
  #               client name / query alias (eg, @relayHash)
  variables: { userId: "100" },
})

Why Persisted Queries? Copy Chapter

Using persisted queries improves the security, efficiency and visibility of your GraphQL system.

Security Copy Section

Persisted queries improve security because you can reject arbitrary GraphQL queries, removing an attack vector from your system. The query database serves a whitelist, so you can be sure that no unexpected queries will hit your system.

For example, after all clients have migrated to persisted queries, you can reject arbitrary GraphQL in production:

# app/controllers/graphql_controller.rb
if Rails.env.production? && params[:query].present?
  # Reject arbitrary GraphQL in production:
  render json: { errors: [{ message: "Raw GraphQL is not accepted" }]}
else
  # ...
end

Efficiency Copy Section

Persisted queries improve the efficiency of your system by reducing HTTP traffic. Instead of repeatedly sending GraphQL over the wire, queries are fetched from the database, so your requests require less bandwidth.

For example, before using persisted queries, the entire query is sent to the server:

But after using persisted queries, only the query identification info is sent to the server:

Visibility Copy Section

Persisted queries improve visibility because you can track GraphQL usage from a single location. OperationStore maintains an index of type, field and argument usage so that you can analyze your traffic.

How it Works Copy Chapter

OperationStore uses tables in your database to store normalized, deduplicated GraphQL strings. The database is immutable: new operations may be added, but operations are never modified or removed.

When clients sync their operations, requests are authenticated, then the incoming GraphQL is validated, normalized, and added to the database if needed. Also, the incoming client name is associated with all operations in the payload.

Then, at runtime, clients send an operation ID to run a persisted query. It looks like this in params:

params[:operationId] # => "relay-app-v1/810c97f6631001..."

OperationStore uses this to fetch the matching operation from the database. From there, the query is evaluated normally.

Getting Started Copy Chapter

See the getting started guide to add OperationStore to your app.

Guides Pagination Overview (`guides/pagination/overview.md`) Copy Section

Overview

GraphQL-Ruby ships with several implementations of Relay's "connection"-style pagination. You can familiarize yourself with connections in Connection Concepts and see how to use them in Using Connections. It also supports custom connection implementations and type definitions, which you can explore in the Custom Connections guide.

GraphQL has its own great pagination docs for further reading.

Guides Subscriptions Overview (`guides/subscriptions/overview.md`) Copy Section

Overview

Subscriptions allow GraphQL clients to observe specific events and receive updates from the server when those events occur. This supports live updates, such as websocket pushes. Subscriptions introduce several new concepts:

• The Subscription type is the entry point for subscription queries
• Subscription classes are resolvers for handing initial subscription requests and subsequent updates
• Triggers begin the update process
• The Implementation provides application-specific methods for executing & delivering updates.
• Broadcasts can send the same GraphQL result to any number of subscribers.

Subscription Type Copy Chapter

subscription is an entry point to your GraphQL schema, like query or mutation. It is defined by your SubscriptionType, a root-level GraphQL::Schema::Object.

Read more in the Subscription Type guide.

Subscription Classes Copy Chapter

GraphQL::Schema::Subscription is a resolver class with subscription-specific behaviors. Each subscription field should be implemented by a subscription class.

Read more in the Subscription Classes guide

Triggers Copy Chapter

After an event occurs in our application, triggers begin the update process by sending a name and payload to GraphQL.

Read more in the Triggers guide.

Implementation Copy Chapter

Besides the GraphQL component, your application must provide some subscription-related plumbing, for example:

• state management: How does your application keep track of who is subscribed to what?
• transport: How does your application deliver payloads to clients?
• queueing: How does your application distribute the work of re-running subscription queries?

Read more in the Implementation guide or check out the ActionCable implementation, Pusher implementation or Ably implementation.

Broadcasts Copy Chapter

By default, the subscription implementations listed above handle each subscription in total isolation. However, this behavior can be optimized by setting up broadcasts. Read more in the Broadcast guide.

Multi-Tenant Copy Chapter

See the Multi-tenant guide for supporting multi-tenancy in GraphQL subscriptions.

Guides Testing Overview (`guides/testing/overview.md`) Copy Section

Overview

So, you've spiked a GraphQL API, and now you're ready to tighten things up and add some proper tests. These guides will help you think about how to ensure stability and compatibility for your GraphQL system.

• Structure testing verifies that schema changes are backwards-compatible. This way, you don't break existing clients.
• Integration testing exercises the various behaviors of the GraphQL system, making sure that it returns the right data to the right clients.
• Testing helpers for running GraphQL fields without writing a whole query

Guide Metadata.Yml (`docs/guide_metadata.yml`) Copy Section

version: 1

Navigation order migrated from the Jekyll `index` frontmatter.

order:
authorization:
- overview
- visibility
- authorization
- can_can_integration
- pundit_integration
- scoping
changesets:
- overview
- installation
- definition
- releases
dataloader:
- overview
- sources
- dataloader
- adopting
- testing
- async_dataloader
- parallelism
defer:
- overview
- setup
- usage
- stream
- graphiql
development:
- getting_started
- development
- faq
- related_projects
- documentation_maintenance
errors:
- overview
- execution_errors
- error_handling
- type_errors
execution:
- next
- migration
fields:
- introduction
- arguments
- resolvers
- validation
- limits
javascript_client:
- overview
- sync
- apollo_subscriptions
- relay_subscriptions
- urql_subscriptions
- graphiql_subscriptions
language_tools:
- visitor
- c_parser
limiters:
- overview
- redis
- active_operations
- runtime
- deployment
mutations:
- mutation_root
- mutation_classes
- mutation_errors
- mutation_authorization
object_cache:
- overview
- schema_setup
- caching
- memcached
- redis
- runtime_considerations
operation_store:
- overview
- getting_started
- active_record_backend
- redis_backend
- client_workflow
- server_management
- access_control
pagination:
- overview
- connection_concepts
- using_connections
- custom_connections
- cursors
- stable_relation_connections
pro:
- home
- installation
- dashboard
- encoders
- privacy
queries:
- executing_queries
- ast_analysis
- phases_of_execution
- complexity_and_depth
- timeout
- multiplex
- lookahead
- tracing
- backtrace_annotations
- logging
- response_extensions
relay:
- range_add
schema:
- definition
- root_types
- generators
- introspection
- lazy_execution
- sdl
- dynamic_types
- object_identification
subscriptions:
- overview
- subscription_classes
- subscription_type
- triggers
- broadcast
- implementation
- action_cable_implementation
- pusher_implementation
- ably_implementation
- multi_tenant
testing:
- overview
- schema_structure
- integration_tests
- helpers
- profiling
type_definitions:
- objects
- scalars
- enums
- input_objects
- interfaces
- unions
- lists
- non_nulls
- extensions
- directives
- field_extensions

Product callouts migrated from the Jekyll `pro` and `enterprise` frontmatter.

products:
pro:
- authorization/can_can_integration
- authorization/pundit_integration
- defer/*
- operation_store/*
- pagination/stable_relation_connections
- pro/dashboard
- pro/encoders
- pro/home
- pro/installation
- subscriptions/ably_implementation
- subscriptions/pusher_implementation
enterprise:
- changesets/*
- limiters/*
- object_cache/*

Redirects.Yml (`docs/redirects.yml`) Copy Section

Guide URLs are generated from the source tree so every existing guide has a

concrete redirect. Add explicit entries for pages that move into an API ref.

guide_source: guides
redirects:

• old_path: /docs/maintenance
  destination:
  kind: page
  value: guides/development/documentation_maintenance.md
• old_path: /guides
  destination:
  kind: page
  value: guides/development/getting_started.md
• old_path: /queries/executing_queries
  destination:
  kind: rdoc_ref
  value: GraphQL::Schema.execute
• old_path: /getting_started
  destination:
  kind: page
  value: guides/development/getting_started.md

Guides Authorization Authorization (`guides/authorization/authorization.md`) Copy Section

Authorization

While a query is running, you can check each object to see whether the current user is authorized to interact with that object. If the user is not authorized, you can handle the case with an error.

Adding Authorization Checks Copy Chapter

Schema members have authorized? methods which will be called during execution:

• Type classes have .authorized?(object, context) class methods
• Fields have #authorized?(object, args, context) instance methods
• Arguments have #authorized?(object, arg_value, context) instance methods
• Mutations and Resolvers have .authorized?(object, context) class methods and #authorized?(args) instance methods
• Enum values have #authorized?(context) instance methods

These methods are called with:

• object: the object from your application which was returned from a field
• args/arg_value: The arguments for a field, or the value of an argument
• context: the query context, based on the hash passed as context:

Object Authorization

When you implement this method to return false, the query will be halted, for example:

class Types::Friendship < Types::BaseObject
  # You can only see the details on a `Friendship`
  # if you're one of the people involved in it.
  def self.authorized?(object, context)
    super && (object.to_friend == context[:viewer] || object.from_friend == context[:viewer])
  end
end

(Always call super to get the default checks, too.)

Now, whenever an object of type Friendship is going to be returned to the client, it will first go through the .authorized? method. If that method returns false, the field will get nil instead of the original object, and you may handle that case with an error (see below).

Field Authorization

Field #authorized? methods are called before resolving a field, for example:

class Types::BaseField < GraphQL::Schema::Field
  # Pass `field ..., require_admin: true` to reject non-admin users from a given field
  def initialize(*args, require_admin: false, **kwargs, &block)
    @require_admin = require_admin
    super(*args, **kwargs, &block)
  end

  def authorized?(obj, args, ctx)
    # if `require_admin:` was given, then require the current user to be an admin
    super && (@require_admin ? ctx[:viewer]&.admin? : true)
  end
end

For this to work, the base field class must be configured with other GraphQL types.

Argument Authorization

Argument #authorized? hooks are called before resolving the field that the argument belongs to. For example:

class Types::BaseArgument < GraphQL::Schema::Argument
  def initialize(*args, require_logged_in: false, **kwargs, &block)
    @require_logged_in = require_logged_in
    super(*args, **kwargs, &block)
  end

  def authorized?(obj, arg_value, ctx)
    super && if @require_logged_in
      ctx[:viewer].present?
    else
      true
    end
  end
end

For this to work, the base argument class must be configured with other GraphQL types.

Mutation Authorization Copy Chapter

See Mutation Authorization in the Mutation Guides.

Enum Value Authorization Copy Chapter

GraphQL::Schema::EnumValue#authorized? is called when client input is received and when the schema returns values to the client.

For authorizing input, if a value's #authorized? method returns false, then a GraphQL::UnauthorizedEnumValueError is raised. It passed to your schema's .unauthorized_object hook, where you can handle it another way if you want.

For authorizing return values, if an outgoing value's #authorized? method returns false, then a GraphQL::Schema::Enum::UnresolvedValueError is raised, which crashes the query. In this case, you should modify your field or resolver to not return this value to an unauthorized viewer. (In this case, the error isn't returned to the viewer because the viewer can't do anything about it -- it's a developer-facing issue instead.)

Handling Unauthorized Objects Copy Chapter

By default, GraphQL-Ruby silently replaces unauthorized objects with nil, as if they didn't exist. You can customize this behavior by implementing Schema.unauthorized_object in your schema class, for example:

class MySchema < GraphQL::Schema
  # Override this hook to handle cases when `authorized?` returns false for an object:
  def self.unauthorized_object(error)
    # Add a top-level error to the response instead of returning nil:
    raise GraphQL::ExecutionError, "An object of type #{error.type.graphql_name} was hidden due to permissions"
  end
end

Now, the custom hook will be called instead of the default one.

If .unauthorized_object returns a non-nil object (and doesn't raise an error), then that object will be used in place of the unauthorized object.

A similar hook is available for unauthorized fields:

class MySchema < GraphQL::Schema
  # Override this hook to handle cases when `authorized?` returns false for a field:
  def self.unauthorized_field(error)
    # Add a top-level error to the response instead of returning nil:
    raise GraphQL::ExecutionError, "The field #{error.field.graphql_name} on an object of type #{error.type.graphql_name} was hidden due to permissions"
  end
end

Guides Authorization Can Can Integration (`guides/authorization/can_can_integration.md`) Copy Section

CanCan Integration

GraphQL::Pro includes an integration for powering GraphQL authorization with CanCan.

Why bother? You could put your authorization code in your GraphQL types themselves, but writing a separate authorization layer gives you a few advantages:

• Since the authorization code isn't embedded in GraphQL, you can use the same logic in non-GraphQL (or legacy) parts of the app.
• The authorization logic can be tested in isolation, so your end-to-end GraphQL tests don't have to cover as many possibilities.

Getting Started Copy Chapter

NOTE: Requires the latest gems, so make sure your Gemfile has:

# For CanCanIntegration:
gem "graphql-pro", ">=1.7.11"
# For list scoping:
gem "graphql", ">=1.8.7"

Then, bundle install.

Whenever you run queries, include :current_user in the context:

context = {
  current_user: current_user,
  # ...
}
MySchema.execute(..., context: context)

Rails Generator Copy Section

If your schema files follow the same convention as rails generate graphql:install, then you can install the CanCan integration with a Rails generator:

$ rails generate graphql:cancan:install

This will insert all the necessary include ...s described below. Alternatively, check the docs below to mix in CanCanIntegration's modules.

Authorizing Objects Copy Chapter

For each object type, you can assign a required action for Ruby objects of that type. To get started, include the ObjectIntegration in your base object class:

# app/graphql/types/base_object.rb
class Types::BaseObject < GraphQL::Schema::Object
  # Add the CanCan integration:
  include GraphQL::Pro::CanCanIntegration::ObjectIntegration
  # By default, require `can :read, ...`
  can_can_action(:read)
  # Or, to require no permissions by default:
  # can_can_action(nil)
end

Now, anyone fetching an object will need can :read, ... for that object.

CanCan configurations are inherited, and can be overridden in subclasses. For example, to allow all viewers to see the Query root type:

class Types::Query < Types::BaseObject
  # Allow anyone to see the query root
  can_can_action nil
end

Bypassing CanCan Copy Section

can_can_action(nil) will override any inherited configuration and skip CanCan checks for an object, field, argument or mutation.

Handling Unauthorized Objects Copy Section

When any CanCan check returns false, the unauthorized object is passed to Schema.unauthorized_object, as described in Handling unauthorized objects.

Scopes Copy Chapter

ActiveRecord::Relation

The CanCan integration adds CanCan's .accessible_by to GraphQL-Ruby's list scoping

To scope lists of interface or union type, include the integration in your base union class and base interface module and set a base can_can_action, if desired:

class BaseUnion < GraphQL::Schema::Union
  include GraphQL::Pro::CanCanIntegration::UnionIntegration
  # To provide a default action for scoping lists:
  can_can_action :read
end

module BaseInterface
  include GraphQL::Schema::Interface
  include GraphQL::Pro::CanCanIntegration::InterfaceIntegration
  # To provide a default action for scoping lists:
  can_can_action :read
end

Array

For Arrays, the CanCan integration will use .select { ... } to filter items using the can_can_action from the lists's type.

Bypassing scopes

To allow an unscoped relation to be returned from a field, disable scoping with scope: false, for example:

# Allow anyone to browse the job postings
field :job_postings, [Types::JobPosting], null: false,
  scope: false

Authorizing Fields Copy Chapter

You can also require certain checks on a field-by-field basis. First, include the integration in your base field class:

# app/graphql/types/base_field.rb
class Types::BaseField < GraphQL::Schema::Field
  # Add the CanCan integration:
  include GraphQL::Pro::CanCanIntegration::FieldIntegration
  # By default, don't require a role at field-level:
  can_can_action nil
end

If you haven't already done so, you should also hook up your base field class to your base object and base interface:

# app/graphql/types/base_object.rb
class Types::BaseObject < GraphQL::Schema::Object
  field_class Types::BaseField
end
# app/graphql/types/base_interface.rb
module Types::BaseInterface
  # ...
  field_class Types::BaseField
end
# app/graphql/mutations/base_mutation.rb
class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  field_class Types::BaseField
end

Then, you can add can_can_action: options to your fields:

class Types::JobPosting < Types::BaseObject
  # Only allow `can :review_applications, JobPosting` users
  # to see who has applied
  field :applicants, [Types::User],
    can_can_action: :review_applicants
end

It will require the named action (:review_applicants) for the object being viewed (a JobPosting).

Authorizing by attribute Copy Section

CanCan 3.0 added attribute-level authorization (pull request). You can leverage this in your field definitions with the can_can_attribute: configuration:

# This will call `.can?(:read, user, :email_address)`
field :email_address, String,
  can_can_action: :read,
  can_can_attribute: :email_address

You could also provide a default value for can_can_attribute in your base field class:

class Types::BaseField
  def initialize(*args, **kwargs, &block)
    # pass all configs to the super class:
    super
    # Then set a new `can_can_attribute` value, if applicable
    if can_can_attribute.nil? && can_can_action.present?
      # `method_sym` is the thing GraphQL-Ruby will use to resolve this field
      can_can_attribute(method_sym)
    end
  end
end

(See GraphQL::Schema::Field for the different values available for defaults.)

Providing a Custom CanCan Subject Copy Section

Authorization checks are skipped whenever the underlying object is nil. This can happen in root query fields, for example, when no root_value: ... is given. To provide a can_can_subject in this case, you can add it as a field configuration:

field :users, Types::User.connection_type, null: false,
  can_can_action: :manage,
  # `:all` will be used instead of `object` (which is `nil`)
  can_can_subject: :all

The configuration above will call can?(:manage, :all) whenever that field is requested.

Authorizing Arguments Copy Chapter

Similar to field-level checks, you can require certain permissions to use certain arguments. To do this, add the integration to your base argument class:

class Types::BaseArgument < GraphQL::Schema::Argument
  # Include the integration and default to no permissions required
  include GraphQL::Pro::CanCanIntegration::ArgumentIntegration
  can_can_action nil
end

Then, make sure your base argument is hooked up to your base field and base input object:

class Types::BaseField < GraphQL::Schema::Field
  argument_class Types::BaseArgument
  # PS: see "Authorizing Fields" to make sure your base field is hooked up to objects, interfaces and mutations
end

class Types::BaseInputObject < GraphQL::Schema::InputObject
  argument_class Types::BaseArgument
end

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  argument_class Types::BaseArgument
end

Now, arguments accept a can_can_action: option, for example:

class Types::Company < Types::BaseObject
  field :employees, Types::Employee.connection_type do
    # Only admins can filter employees by email:
    argument :email, String, required: false, can_can_action: :admin
  end
end

This will check for can :admin, Company (or a similar rule for the company being queried) for the current user.

Authorizing Mutations Copy Chapter

There are a few ways to authorize GraphQL mutations with the CanCan integration:

• Add a mutation-level roles
• Run checks on objects loaded by ID

Also, you can configure unauthorized object handling

Setup

Add MutationIntegration to your base mutation, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  include GraphQL::Pro::CanCanIntegration::MutationIntegration

  # Also, to use argument-level authorization:
  argument_class Types::BaseArgument
end

Also, you'll probably want a BaseMutationPayload where you can set a default role:

class Types::BaseMutationPayload < Types::BaseObject
  # If `BaseObject` requires some permissions, override that for mutation results.
  # Assume that anyone who can run a mutation can read their generated result types.
  can_can_action nil
end

And hook it up to your base mutation:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  object_class Types::BaseMutationPayload
  field_class Types::BaseField
end

Mutation-level roles

Each mutation can have a class-level can_can_action which will be checked before loading objects or resolving, for example:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  can_can_action :run_mutation
end

In the example above, can :run_mutation, Mutations::PromoteEmployee will be checked before running the mutation. (The currently-running instance of Mutations::PromoteEmployee is passed to the ability checker.)

Authorizing Loaded Objects

Mutations can automatically load and authorize objects by ID using the loads: option.

Beyond the normal object reading permissions, you can add an additional role for the specific mutation input using a can_can_action: option:

class Mutations::FireEmployee < Mutations::BaseMutation
  argument :employee_id, ID,
    loads: Types::Employee,
    can_can_action: :supervise,
end

In the case above, the mutation will halt unless the can :supervise, ... check returns true. (The fetched instance of Employee is passed to the ability checker.)

Unauthorized Mutations

By default, an authorization failure in a mutation will raise a Ruby exception. You can customize this by implementing #unauthorized_by_can_can(owner, value) in your base mutation, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  def unauthorized_by_can_can(owner, value)
    # No error, just return nil:
    nil
  end
end

The method is called with:

• owner: the GraphQL::Schema::Argument instance or mutation class whose role was not satisfied
• value: the object which didn't pass for context[:current_user]

Since it's a mutation method, you can also access context in that method.

Whatever that method returns will be treated as an early return value for the mutation, so for example, you could return errors as data:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  field :errors, [String]

  def unauthorized_by_can_can(owner, value)
    # Return errors as data:
    { errors: ["Missing required permission: #{owner.can_can_action}, can't access #{value.inspect}"] }
  end
end

Authorizing Resolvers Copy Chapter

Resolvers are authorized just like mutations, and require similar setup:

# app/graphql/resolvers/base_resolver.rb
class Resolvers::BaseResolver < GraphQL::Schema::Resolver
  include GraphQL::Pro::CanCanIntegration::ResolverIntegration
  argument_class BaseArgument
  # can_can_action(nil) # to disable authorization by default
end

Beyond that, see Authorizing Mutations above for further details.

Custom Abilities Class Copy Chapter

By default, the integration will look for a top-level ::Ability class.

If you're using a different class, provide an instance ahead-of-time as context[:can_can_ability]

For example, you could always add one in your schema's #execute method:

class MySchema < GraphQL::Schema
  # Override `execute` to provide a custom Abilities instance for the CanCan integration
  def self.execute(*args, context: {}, **kwargs)
    # Assign `context[:can_can_ability]` to an instance of our custom class
    context[:can_can_ability] = MyAuthorization::CustomAbilitiesClass.new(context[:current_user])
    super
  end
end

Guides Authorization Pundit Integration (`guides/authorization/pundit_integration.md`) Copy Section

Pundit Integration

GraphQL::Pro includes an integration for powering GraphQL authorization with Pundit policies.

Why bother? You could put your authorization code in your GraphQL types themselves, but writing a separate authorization layer gives you a few advantages:

• Since the authorization code isn't embedded in GraphQL, you can use the same logic in non-GraphQL (or legacy) parts of the app.
• The authorization logic can be tested in isolation, so your end-to-end GraphQL tests don't have to cover as many possibilities.

Getting Started Copy Chapter

NOTE: Requires the latest gems, so make sure your Gemfile has:

# For PunditIntegration:
gem "graphql-pro", ">=1.7.9"
# For list scoping:
gem "graphql", ">=1.8.7"

Then, bundle install.

Whenever you run queries, include :current_user in the context:

context = {
  current_user: current_user,
  # ...
}
MySchema.execute(..., context: context)

Rails Generator Copy Section

If your schema files follow the same convention as rails generate graphql:install, then you can install the Pundit integration with a Rails generator:

$ rails generate graphql:pundit:install

This will insert all the necessary include ...s described below. Alternatively, check the docs below to mix in PunditIntegration's modules.

Authorizing Objects Copy Chapter

You can specify Pundit roles that must be satisfied in order for viewers to see objects of a certain type. To get started, include the ObjectIntegration in your base object class:

# app/graphql/types/base_object.rb
class Types::BaseObject < GraphQL::Schema::Object
  # Add the Pundit integration:
  include GraphQL::Pro::PunditIntegration::ObjectIntegration
  # By default, require staff:
  pundit_role :staff
  # Or, to require no permissions by default:
  # pundit_role nil
end

Now, anyone trying to read a GraphQL object will have to pass the #staff? check on that object's policy.

Then, each child class can override that parent configuration. For example, allow all viewers to read the Query root:

class Types::Query < Types::BaseObject
  # Allow anyone to see the query root
  pundit_role nil
end

Policies and Methods

For each object returned by GraphQL, the integration matches it to a policy and method.

The policy is found using Pundit.policy!, which looks up a policy using the object's class name. (This can be customized, see below.)

Then, GraphQL will call a method on the policy to see whether the object is permitted or not. This method is assigned in the object class, for example:

class Types::Employee < Types::BaseObject
  # Only show employee objects to their bosses,
  # or when that employee is the current viewer
  pundit_role :employer_or_self
  # ...
end

That configuration will call #employer_or_self? on the corresponding Pundit policy.

Custom Policy Class

By default, the integration uses Pundit.policy!(current_user, object) to find a policy. You can specify a policy class using pundit_policy_class(...):

class Types::Employee < Types::BaseObject
  pundit_policy_class(Policies::CustomEmployeePolicy)
  # Or, you could use a string:
  # pundit_policy_class("Policies::CustomEmployeePolicy")
end

For really custom policy lookup, see Custom Policy Lookup below.

Bypassing Policies

The integration requires that every object with a pundit_role has a corresponding policy class. To allow objects to skip authorization, you can pass nil as the role:

class Types::PublicProfile < Types::BaseObject
  # Anyone can see this
  pundit_role nil
end

Handling Unauthorized Objects

When any Policy method returns false, the unauthorized object is passed to Schema.unauthorized_object, as described in Handling unauthorized objects.

Scopes Copy Chapter

The Pundit integration adds Pundit scopes to GraphQL-Ruby's list scoping feature. Any list or connection will be scoped. If a scope is missing, the query will crash rather than risk leaking unfiltered data.

To scope lists of interface or union type, include the integration in your base union class and base interface module:

class BaseUnion < GraphQL::Schema::Union
  include GraphQL::Pro::PunditIntegration::UnionIntegration
end

module BaseInterface
  include GraphQL::Schema::Interface
  include GraphQL::Pro::PunditIntegration::InterfaceIntegration
end

Bypassing scopes

To allow an unscoped relation to be returned from a field, disable scoping with scope: false, for example:

# Allow anyone to browse the job postings
field :job_postings, [Types::JobPosting], null: false,
  scope: false

Authorizing Fields Copy Chapter

You can also require certain checks on a field-by-field basis. First, include the integration in your base field class:

# app/graphql/types/base_field.rb
class Types::BaseField < GraphQL::Schema::Field
  # Add the Pundit integration:
  include GraphQL::Pro::PunditIntegration::FieldIntegration
  # By default, don't require a role at field-level:
  pundit_role nil
end

If you haven't already done so, you should also hook up your base field class to your base object and base interface:

# app/graphql/types/base_object.rb
class Types::BaseObject < GraphQL::Schema::Object
  field_class Types::BaseField
end
# app/graphql/types/base_interface.rb
module Types::BaseInterface
  # ...
  field_class Types::BaseField
end
# app/graphql/mutations/base_mutation.rb
class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  field_class Types::BaseField
end

Then, you can add pundit_role: options to your fields:

class Types::JobPosting < Types::BaseObject
  # Allow signed-in users to browse listings
  pundit_role :signed_in

  # But, only allow `JobPostingPolicy#staff?` users to see
  # who has applied
  field :applicants, [Types::User],
    pundit_role: :staff
end

It will call the named role (eg, #staff?) on the parent object's policy (eg JobPostingPolicy).

Custom Policy Class

You can override the policy class for a field using pundit_policy_class:, for example:

class Types::JobPosting < Types::BaseObject
  # Only allow `ApplicantsPolicy#staff?` users to see
  # who has applied
  field :applicants, [Types::User],
    pundit_role: :staff,
    pundit_policy_class: ApplicantsPolicy
    # Or with a string:
    # pundit_policy_class: "ApplicantsPolicy"
end

This will initialize an ApplicantsPolicy with the parent object (a Job) and call #staff? on it.

For really custom policy lookup, see Custom Policy Lookup below.

Authorizing Arguments Copy Chapter

Similar to field-level checks, you can require certain permissions to use certain arguments. To do this, add the integration to your base argument class:

class Types::BaseArgument < GraphQL::Schema::Argument
  # Include the integration and default to no permissions required
  include GraphQL::Pro::PunditIntegration::ArgumentIntegration
  pundit_role nil
end

Then, make sure your base argument is hooked up to your base field and base input object:

class Types::BaseField < GraphQL::Schema::Field
  argument_class Types::BaseArgument
  # PS: see "Authorizing Fields" to make sure your base field is hooked up to objects, interfaces and mutations
end

class Types::BaseInputObject < GraphQL::Schema::InputObject
  argument_class Types::BaseArgument
end

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  argument_class Types::BaseArgument
end

Now, arguments accept a pundit_role: option, for example:

class Types::Company < Types::BaseObject
  field :employees, Types::Employee.connection_type do
    # Only admins can filter employees by email:
    argument :email, String, required: false, pundit_role: :admin
  end
end

The role will be called on the parent object's policy, for example CompanyPolicy#admin? in the case above.

Authorizing Mutations Copy Chapter

There are a few ways to authorize GraphQL mutations with the Pundit integration:

• Add a mutation-level roles
• Run checks on objects loaded by ID

Also, you can configure unauthorized object handling

Setup

Add MutationIntegration to your base mutation, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  include GraphQL::Pro::PunditIntegration::MutationIntegration

  # Also, to use argument-level authorization:
  argument_class Types::BaseArgument
end

Also, you'll probably want a BaseMutationPayload where you can set a default role:

class Types::BaseMutationPayload < Types::BaseObject
  # If `BaseObject` requires some permissions, override that for mutation results.
  # Assume that anyone who can run a mutation can read their generated result types.
  pundit_role nil
end

And hook it up to your base mutation:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  object_class Types::BaseMutationPayload
  field_class Types::BaseField
end

Mutation-level roles

Each mutation can have a class-level pundit_role which will be checked before loading objects or resolving, for example:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  pundit_role :admin
end

In the example above, PromoteEmployeePolicy#admin? will be checked before running the mutation.

Custom Policy Class

By default, Pundit uses the mutation's class name to look up a policy. You can override this by defining pundit_policy_class on your mutation:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  pundit_policy_class ::UserPolicy
  pundit_role :admin
end

Now, the mutation will check UserPolicy#admin? before running.

For really custom policy lookup, see Custom Policy Lookup below.

Authorizing Loaded Objects

Mutations can automatically load and authorize objects by ID using the loads: option.

Beyond the normal object reading permissions, you can add an additional role for the specific mutation input using a pundit_role: option:

class Mutations::FireEmployee < Mutations::BaseMutation
  argument :employee_id, ID,
    loads: Types::Employee,
    pundit_role: :supervisor,
end

In the case above, the mutation will halt unless the EmployeePolicy#supervisor? method returns true.

Unauthorized Mutations

By default, an authorization failure in a mutation will raise a Ruby exception. You can customize this by implementing #unauthorized_by_pundit(owner, value) in your base mutation, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  def unauthorized_by_pundit(owner, value)
    # No error, just return nil:
    nil
  end
end

The method is called with:

• owner: the GraphQL::Schema::Argument or mutation class whose role was not satisfied
• value: the object which didn't pass for context[:current_user]

Since it's a mutation method, you can also access context in that method.

Whatever that method returns will be treated as an early return value for the mutation, so for example, you could return errors as data:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  field :errors, [String]

  def unauthorized_by_pundit(owner, value)
    # Return errors as data:
    { errors: ["Missing required permission: #{owner.pundit_role}, can't access #{value.inspect}"] }
  end
end

Authorizing Resolvers Copy Chapter

Resolvers are authorized just like mutations, and require similar setup:

# app/graphql/resolvers/base_resolver.rb
class Resolvers::BaseResolver < GraphQL::Schema::Resolver
  include GraphQL::Pro::PunditIntegration::ResolverIntegration
  argument_class BaseArgument
  # pundit_role nil # to disable authorization by default
end

Beyond that, see Authorizing Mutations above for further details.

Custom Policy Lookup Copy Chapter

By default, the integration uses Pundit's top-level methods to interact with policies:

• Pundit.policy!(context[:current_user], object) is called to find a policy instance
• Pundit.policy_scope!(context[:current_user], items) is called to filter items

Custom Policy Methods Copy Section

You can implement a custom lookup by defining the following methods in your schema:

• pundit_policy_class_for(object, context) to return a policy class (or raise an error if one isn't found)
• pundit_role_for(object, context) to return a role method (Symbol), or nil to bypass authorization
• scope_by_pundit_policy(context, items) to apply a scope to items (or raise an error if one isn't found)

Since different objects have different lifecycles, the hooks are installed slightly different ways:

• Your base argument, field, and mutation classes should have instance methods with those names
• Your base type classes should have class methods with that name

Here's an example of how the custom hooks can be installed:

module CustomPolicyLookup
  # Lookup policies in the `SystemAdmin::` namespace for system_admin users
  # @return [Class]
  def pundit_policy_class_for(object, context)
    current_user = context[:current_user]
    if current_user.system_admin?
      SystemAdmin.const_get("#{object.class.name}Policy")
    else
      super
    end
  end

  # Require admin permissions if the object is pending_approval
  def pundit_role_for(object, context)
    if object.pending_approval?
      :admin
    else
      super # fall back to the normally-configured role
    end
  end
end

# Add policy hooks as class methods
class Types::BaseObject < GraphQL::Schema::Object
  extend CustomPolicyLookup
end
class Types::BaseUnion < GraphQL::Schema::Union
  extend CustomPolicyLookup
end
module Types::BaseInterface
  include GraphQL::Schema::Interface
  # Add this as a class method that will be "inherited" by other interfaces:
  definition_methods do
    include CustomPolicyLookup
  end
end

# Add policy hooks as instance methods
class Types::BaseField < GraphQL::Schema::Field
  include CustomPolicyLookup
end
class Types::BaseArgument < GraphQL::Schema::Argument
  include CustomPolicyLookup
end
class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  include CustomPolicyLookup
end

One Policy Per Class Copy Section

Another good approach is to have one policy per class. You can implement policy_class_for(object, context) to look up a policy within the class, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  def policy_class_for(_object, _context)
    # Look up a nested `Policy` constant:
    self.class.const_get(:Policy)
  end
end

Then, each mutation can define its policy inline, for example:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  # This will be found by `BaseMutation.policy_class`, defined above:
  class Policy
    # ...
  end

  pundit_role :admin
end

Now, Mutations::PromoteEmployee::Policy#admin? will be checked before running the mutation.

Custom User Lookup Copy Chapter

By default, the Pundit integration looks for the current user in context[:current_user]. You can override this by implementing #pundit_user on your custom query context class. For example:

# app/graphql/query_context.rb
class QueryContext < GraphQL::Query::Context
  def pundit_user
    # Lookup `context[:viewer]` instead:
    self[:viewer]
  end
end

Then be sure to hook up your custom class in the schema:

class MySchema < GraphQL::Schema
  context_class(QueryContext)
end

Then, the Pundit integration will use your def pundit_user to get the current user at runtime.

Guides Authorization Scoping (`guides/authorization/scoping.md`) Copy Section

Scoping

Scoping is a complementary consideration to authorization. Rather than checking "can this user see this thing?", scoping takes a list of items filters it to the subset which is appropriate for the current viewer and context.

For similar features, see Pundit scopes and Cancan's .accessible_by.

`scope:` option Copy Chapter

Fields accept a scope: option to enable (or disable) scoping, for example:

field :products, [Types::Product], scope: true
# Or
field :all_products, [Types::Product], scope: false

For list and connection fields, scope: true is the default. For all other fields, scope: false is the default. You can override this by using the scope: option.

`.scope_items(items, ctx)` method Copy Chapter

Type classes may implement .scope_items(items, ctx). This method is called when a field has scope: true. For example,

field :products, [Types::Product] # has `scope: true` by default

Will call:

class Types::Product < Types::BaseObject
  def self.scope_items(items, context)
    # filter items here
  end
end

The method should return a new list with only the appropriate items for the current context.

Bypassing object-level authorization Copy Chapter

If you know that any items returned from .scope_items should be visible to the current client, you can skip the normal .authorized?(obj, ctx) checks by configuring reauthorize_scoped_objects(false) in your type definition. For example:

class Types::Product < Types::BaseObject
  # Check that singly-loaded objects are visible to the current viewer
  def self.authorized?(object, context)
    super && object.visible_to?(context[:viewer])
  end

  # Filter any list to only include objects that are visible to the current viewer
  def self.scope_items(items, context)
    items = super(items, context)
    items.visible_for(context[:viewer])
  end

  # If an object of this type was returned from `.scope_items`,
  # don't call `.authorized?` with it.
  reauthorize_scoped_objects(false)
end

Guides Authorization Visibility (`guides/authorization/visibility.md`) Copy Section

Visibility

With GraphQL-Ruby, it's possible to hide parts of your schema from some users. This isn't exactly part of the GraphQL spec, but it's roughly within the bounds of the spec.

Here are some reasons you might want to hide parts of your schema:

• You don't want non-admin users to know about administration functions of the schema.
• You're developing a new feature and want to make a gradual release to only a few users first.

Hiding Parts of the Schema Copy Chapter

To start limiting visibility of your schema, add the plugin:

class MySchema < GraphQL::Schema
  # ...
  use GraphQL::Schema::Visibility # see below for options
end

Then, you can customize the visibility of parts of your schema by reimplementing various visible? methods:

• Type classes have a .visible?(context) class method
• Fields and arguments have a #visible?(context) instance method
• Enum values have #visible?(context) instance method
• Mutation classes have a .visible?(context) class method

These methods are called with the query context, based on the hash you pass as context:. If the method returns false, then that member of the schema will be treated as though it doesn't exist for the entirety of the query. That is:

• In introspection, the member will not be included in the result
• In normal queries, if a query references that member, it will return a validation error, since that member doesn't exist

Visibility Profiles Copy Chapter

You can use named profiles to cache your schema's visibility modes. For example:

use GraphQL::Schema::Visibility, profiles: {
  # mode_name => example_context_hash
  public: { public: true },
  beta: { public: true, beta: true },
  internal_admin: { internal_admin: true }
}

Then, you can run queries with context[:visibility_profile] equal to one of the pre-defined profiles. When you do, GraphQL-Ruby will create a cached set of types for named profile. .visible? will only be called with the context hash passed to profiles: ....

The profile contexts passed to profiles will have visibility_profile: ... added to them, then they're frozen by GraphQL-Ruby.

Preloading profiles Copy Section

By default, GraphQL-Ruby will preload all named visibility profiles when Rails.env.production? is present and true. You can manually set this option by passing use ... preload: true (or false). Enable preloading in production to reduce latency of the first request to each visibility profile. Disable preloading in development to speed up application boot.

Dynamic profiles Copy Section

When you provide named visibility profiles, context[:visibility_profile] is required for query execution. You can also permit dynamic visibility for queries which don't have that key set by passing use ..., dynamic: true. You could use this to support backwards compatibility or when visibility calculations are too complex to predefine.

When no named profiles are defined, all queries use dynamic visibility.

Object Visibility Copy Chapter

Let's say you're working on a new feature which should remain secret for a while. You can implement .visible? in a type:

class Types::SecretFeature < Types::BaseObject
  def self.visible?(context)
    # only show it to users with the secret_feature enabled
    super && context[:viewer].feature_enabled?(:secret_feature)
  end
end

(Always call super to inherit the default behavior.)

Now, the following bits of GraphQL will return validation errors:

• Fields that return SecretFeature, eg query { findSecretFeature { ... } }
• Fragments on SecretFeature, eg Fragment SF on SecretFeature

And in introspection:

• __schema { types { ... } } will not include SecretFeature
• __type(name: "SecretFeature") will return nil
• Any interfaces or unions which normally include SecretFeature will not include it
• Any fields that return SecretFeature will be excluded from introspection

Field Visibility Copy Chapter

class Types::BaseField < GraphQL::Schema::Field
  # Pass `field ..., require_admin: true` to hide this field from non-admin users
  def initialize(*args, require_admin: false, **kwargs, &block)
    @require_admin = require_admin
    super(*args, **kwargs, &block)
  end

  def visible?(ctx)
    # if `require_admin:` was given, then require the current user to be an admin
    super && (@require_admin ? ctx[:viewer]&.admin? : true)
  end
end

For this to work, the base field class must be configured with other GraphQL types.

Argument Visibility Copy Chapter

class Types::BaseArgument < GraphQL::Schema::Argument
  # If `require_logged_in: true` is given, then this argument will be hidden from logged-out viewers
  def initialize(*args, require_logged_in: false, **kwargs, &block)
    @require_logged_in = require_logged_in
    super(*args, **kwargs, &block)
  end

  def visible?(ctx)
    super && (@require_logged_in ? ctx[:viewer].present? : true)
  end
end

For this to work, the base argument class must be configured with other GraphQL types.

Opting Out Copy Chapter

By default, GraphQL-Ruby always runs visibility checks. You can opt out of this by adding to your schema class:

class MySchema < GraphQL::Schema
  # ...
  # Opt out of GraphQL-Ruby's visibility feature:
  use GraphQL::Schema::AlwaysVisible
end

For big schemas, this can be a worthwhile speed-up.

Migration Notes Copy Chapter

GraphQL::Schema::Visibility is a new implementation of visibility in GraphQL-Ruby. It has some slight differences from the previous implementation (GraphQL::Schema::Warden):

• Visibility speeds up Rails app boot because it doesn't require all types to be loaded during boot and only loads types as they are used by queries.
• Visibility supports predefined, reusable visibility profiles which speeds up queries using complicated visible? checks.
• Visibility hides types differently in a few edge cases:
  • Previously, Warden hid interface and union types which had no possible types. Visibility doesn't check possible types (in order to support performance improvements), so those types must return false for visible? in the same cases where all possible types were hidden. Otherwise, that interface or union type will be visible but have no possible types.
  • When an object type is connected to the schema as a field return type or a union member, and also implements and interface, if the object type's other connection(s) to the schema are hidden, then it won't appear as an implementer of that interface unless it's registered with orphan_types (either by the schema or interface). Warden used a "global" map of types so it could discover object types in this case, but Visibility doesn't have that global map. (Since time of writing, Visibility does have some global type tracking, so maybe this could be fixed.)
• When Visibility is used, several (Ruby-level) Schema introspection methods don't work because the caches they draw on haven't been calculated (Schema.references_to, Schema.union_memberships). If you're using these, please get in touch so that we can find a way forward.
• If you programmatically generate your GraphQL schema (instead of using plain-Ruby .rb files), you must ensure that generation is threadsafe. Otherwise, definitions may be malformed in Rails development mode when multithreaded. (Rails eager-loads all files in production mode, so this concern doesn't exist there.)

Migration Mode Copy Section

You can use use GraphQL::Schema::Visibility, ... migration_errors: true to enable migration mode. In this mode, GraphQL-Ruby will make visibility checks with both Visibility and Warden and compare the result, raising a descriptive error when the two systems return different results. As you migrate to Visibility, enable this mode in test to find any unexpected discrepancies.

Sometimes, there's a discrepancy that is hard to resolve but doesn't make any real difference in application behavior. To address these cases, you can use these flags in context:

• context[:visibility_migration_running] = true is set in the main query context.
• context[:visibility_migration_warden_running] = true is set in the duplicate context which is passed to a Warden instance.
• If you set context[:skip_migration_error] = true, then no migration error will be raised for that query.

You can use these flags to conditionally handle edge cases that should be ignored in testing.

Guides Changesets Definition (`guides/changesets/definition.md`) Copy Section

Defining Changesets

After installing Changeset integrations in your schema, you can create Changesets which modify parts of the schema. Changesets extend GraphQL::Enterprise::Changeset and include a release string. Once a Changeset class is defined, it can be referenced with added_in: ... or removed_in: ... configurations in the schema.

Note: Before GraphQL-Enterprise 1.3.0, Changesets were configured with modifies ... blocks. These blocks are still supported and you can find the documentation for that API on GitHub.

Changeset Classes Copy Chapter

This Changeset will be available to any client whose context[:changeset_version] is on or after 2020-12-01:

# app/graphql/changesets/deprecate_recipe_flag.rb
class Changesets::DeprecateRecipeTags < GraphQL::Enterprise::Changeset
  release "2020-12-01"
end

Additionally, Changesets must be released for their changes to be published.

Publishing with `added_in:` Copy Chapter

New things can be published in a changeset by adding added_in: SomeChangeset to their configuration. For example, to add a new argument to a field:

field :search_recipes, [Types::Recipe] do
  argument :query, String
  argument :tags, [Types::RecipeTag], required: false, added_in: Changesets::AddRecipeTags
end

You can also provide a replacement implementation by using added_in:. When a new definition has the same name as an existing definition, it implicitly replaces the previous definition in new versions of the API. For example:

field :rating, Integer, "A 1-5 score for this recipe" # This definition will be superseded by the following one
field :rating, Float, "A 1.0-5.0 score for this recipe", added_in: Changesets::FloatingPointRatings

Here, a new implementation for rating will be used when clients requests an API version that includes Changesets::FloatingPointRatings. (If the client requests a version before that changeset, then the preceding implementation would be used instead.)

Removing with `removed_in:` Copy Chapter

A removed_in: configuration removes something in the named changeset. For example, these enum values are replaced with more clearly-named ones:

class Types::RecipeTag < Types::BaseEnum
  # These are replaced by *_HEAT below:
  value :SPICY, removed_in: Changesets::ClarifyHeatTags
  value :MEDIUM, removed_in: Changesets::ClarifyHeatTags
  value :MILD, removed_in: Changesets::ClarifyHeatTags
  # These new tags are more clear:
  value :SPICY_HEAT, added_in: Changesets::ClarifyHeatTags
  value :MEDIUM_HEAT, added_in: Changesets::ClarifyHeatTags
  value :MILD_HEAT, added_in: Changesets::ClarifyHeatTags
end

If something has been defined several times, a removed_in: configuration removes all definitions:

class Mutations::SubmitRecipeRating < Mutations::BaseMutation
  # This is replaced in future API versions by the following argument
  argument :rating, Integer
  # This replaces the previous, but in another future version,
  # it is removed completely (and so is the previous one)
  argument :rating, Float, added_in: Changesets::FloatingPointRatings, removed_in: Changesets::RemoveRatingsCompletely
end

Examples Copy Chapter

See below for the different kind of modifications you can make in a changeset:

• Fields: adding, modifying, and removing fields
• Arguments: adding, modifying, and removing arguments
• Enum values: adding, modifying, and removing arguments
• Unions: adding or removing object types from a union
• Interfaces: adding or removing interface implementations from object types
• Types: changing one type definition for another
• Runtime: choosing a behavior at runtime based on the current request and changeset

Fields Copy Section

To add or redefine a field, use field(..., added_in: ...), including all configuration values for the new implementation (see the GraphQL::Schema::Field API). The definition given here will override the previous definition (if there was one) whenever this Changeset applies.

class Types::Recipe < Types::BaseObject
  # This new field is available when `context[:changeset_version]`
  # is on or after the release date of `AddRecipeTags`
  field :tags, [Types::RecipeTag], added_in: Changeset::AddRecipeTags
end

To remove a field, add a removed_in: ... configuration to the last definition of the field:

class Types::Recipe < Types::BaseObject
  # Even after migrating to floating point values,
  # the "rating" feature never took off,
  # so we removed it entirely eventually.
  field :rating, Integer
  field :rating, Float, added_in: Changeset::FloatingPointRatings,
    removed_in: Changeset::RemoveRatings
end

When a field is removed, queries that request that field will be invalid, unless the client has requested a previous API version where the field is still available.

Arguments Copy Section

You can add, redefine, or remove arguments that belong to fields, input objects, or resolvers. Use added_in: ... to provide a new (or updated) definition for an argument, for example:

class Types::RecipesFilter < Types::BaseInputObject
  argument :rating, Integer
  # This new definition is available when
  # the client's `context[:changeset_version]` includes `FloatingPointRatings`
  argument :rating, Float, added_in: Changesets::FloatingPointRatings
end

To remove an argument entirely, add a removed_in: ... configuration to the last definition. It will remove all implementations for that argument. For example:

class Mutations::SubmitRating < Mutations::BaseMutation
  # Remove this because it's irrelevant:
  argument :phone_number, String, removed_in: Changesets::StopCollectingPersonalInformation
end

When arguments are removed, the schema will reject any queries which use them unless the client has requested a previous API version where the argument is still allowed.

Enum Values Copy Section

With Changesets, you can add, redefine, or remove enum values. To add a new value (or provide a new implementation for a value), include added_in: in the value(...) configuration:

class Types::RecipeTag < Types::BaseEnum
  # This enum will accept and return `KETO` only when the client's API version
  # includes `AddKetoDietSupport`'s release date.
  value :KETO, added_in: Changesets::AddKetoDietSupport
end

Values can be removed with removed_in:, for example:

class Types::RecipeTag < Types::BaseEnum
  # Old API versions will serve this value;
  # new versions won't accept it or return it.
  value :GRAPEFRUIT_DIET, removed_in: Changesets::RemoveLegacyDiets
end

When enum values are removed, they won't be accepted as input and they won't be allowed as return values from fields unless the client has requested a previous API version where those values are still allowed.

Unions Copy Section

You can add to or remove from a union's possible types. To release a new union member, include added_in: in the possible_types configuration:

class Types::Cookable < Types::BaseUnion
 possible_types Types::Recipe, Types::Ingredient
 # Add this to the union when clients opt in to our new feature:
 possible_types Types::Cuisine, added_in: Changeset::ReleaseCuisines

To remove a member from a union, move it to a possible_types call with removed_in: ...:

# Stop including this in the union in new API versions:
possible_types Types::Chef, removed_in: Changeset::LessChefHype

When a possible type is removed, it will not be associated with the union type in introspection queries or schema dumps.

Interfaces Copy Section

You can add to or remove from an object type's interface definitions. To add one or more interface implementations, use implements(..., added_in:). This will add the interface and its fields to the object whenever this Changeset is active, for example:

class Types::Recipe < Types::BaseObject
  # Add this new implementation in new API versions only:
  implements Types::RssSubject, added_in: Changesets::AddRssSupport
end

To remove one or more more interface implementations, add removed_in: to the implements ... configuration, for example:

implements Types::RssSubject,
    added_in: Changesets::AddRssSupport,
    # Sadly, nobody seems to want to use this,
    # so we removed it all:
    removed_in: Changesets::RemoveRssSupport

When an interface implementation is removed, then the interface will not be associated with the object in introspection queries or schema dumps. Also, any fields inherited from the interface will be hidden from clients. (If the object defines the field itself, it will still be visible.)

Types Copy Section

Using Changesets, it's possible to define a new type using the same name as an old type. (Only one type per name is allowed for each query, but different queries can use different types for the same name.)

First, to define two types with the same name, make two different type definitions. One of them will have to use graphql_name(...) to specify the conflicting type name. For example, to migrate an enum type to an object type, define two types:

# app/graphql/types/legacy_recipe_flag.rb

# In the old version of the schema, "recipe tags" were limited to defined set of values.
# This enum was renamed from `Types::RecipeTag`, then `graphql_name("RecipeTag")`
# was added for GraphQL.
class Types::LegacyRecipeTag < Types::BaseEnum
  graphql_name "RecipeTag"
  # ...
end

# app/graphql/types/recipe_flag.rb

# But in the new schema, each tag is a full-fledged object with fields of its own
class Types::RecipeTag < Types::BaseObject
  field :name, String, null: false
  field :is_vegetarian, Boolean, null: false
  # ...
end

Then, add or update fields or arguments to use the new type instead of the old one. For example:

class Types::Recipe < Types::BaseObject

# Change this definition to point at the newly-renamed _legacy_ type
# (It's the same type definition, but the Ruby class has a new name)
-   field :tags, [Types::RecipeTag]
+   field :tags, [Types::LegacyRecipeTag]

# And add a new field for the new type:
+   field :tags, [Types::RecipeTag], added_in: Changesets::MigrateRecipeTagToObject
  end

With that Changeset, Recipe.tags will return an object type instead of an enum type. Clients requesting older versions will still receive enum values from that field.

The resolver will probably need an update, too, for example:

class Types::Recipe < Types::BaseObject
  # Here's the original definition which returns enum values:
  field :tags, [Types::LegacyRecipeTag], null: false
  # Here's the new definition which replaces the previous one on new API versions:
  field :tags, [Types::RecipeTag], null: false, added_in: Changesets::MigrateRecipeTagToObject

  def flags
    all_flag_objects = object.flag_objects
    if Changesets::MigrateRecipeTagToObject.active?(context)
      # Here's the new behavior, returning full objects:
      all_flag_objects
    else
      # Convert this to enum values, for legacy behavior:
      all_flag_objects.map { |f| f.name.upcase }
    end
  end
end

That way, legacy clients will continue to receive enum values while new clients will receive objects.

Runtime Copy Chapter

While a query is running, you can check if a changeset applies by using its .active?(context) method. For example:

class Types::Recipe
  field :flag, Types::RecipeFlag, null: true

  def flag
    # Check if this changeset applies to the current request:
    if Changesets::DeprecateRecipeFlag.active?(context)
      Stats.count(:deprecated_recipe_flag, context[:viewer])
    end
    # ...
  end
end

Besides observability, you can use a runtime check when a resolver needs to pick a different behavior depending on the API version.

After defining a changeset, add it to the schema to release it.

Guides Changesets Installation (`guides/changesets/installation.md`) Copy Section

Installing Changesets

Changesets require some updates to the schema (to define changesets) and some updates to your controller (to receive version headers from clients).

Schema Setup Copy Chapter

To get started with GraphQL-Enterprise Changesets, you have to add them to your schema. They're added in several places:

• To support versioning arguments, add the ArgumentIntegration to your base argument:

  ruby Copy

  # app/graphql/types/base_argument.rb
  class Types::BaseArgument < GraphQL::Schema::Argument
    include GraphQL::Enterprise::Changeset::ArgumentIntegration
  end

  Also, make sure that your BaseField, BaseInputObject, BaseResolver, and BaseMutation have argument_class(Types::BaseArgument) configured in them.

• To support versioning fields, add the FieldIntegration to your base field:

  ruby Copy

  # app/graphql/types/base_field.rb
  class Types::BaseField < GraphQL::Schema::Field
    include GraphQL::Enterprise::Changeset::FieldIntegration
    argument_class(Types::BaseArgument)
  end

  Also, make sure that your BaseObject, BaseInterface, and BaseMutation have field_class(Types::BaseField) configured in them.

• To support versioning enum values, add the EnumValueIntegration to your base enum value:

  ruby Copy

  # app/graphql/types/base_enum_value.rb
  class Types::BaseEnumValue < GraphQL::Schema::EnumValue
    include GraphQL::Enterprise::Changeset::EnumValueIntegration
  end

  Also, make sure that your BaseEnum has enum_value_class(Types::BaseEnumValue) configured in it.

• To support versioning union memberships and interface implementations, add the TypeMembershipIntegration to your base type membership:

  ruby Copy

  # app/graphql/types/base_type_membership.rb
  class Types::BaseTypeMembership < GraphQL::Schema::TypeMembership
    include GraphQL::Enterprise::Changeset::TypeMembershipIntegration
  end

  Also, make sure that your BaseUnion and BaseInterface have type_membership_class(Types::BaseTypeMembership) configured in it. (TypeMemberships are used by GraphQL-Ruby to link object types to the union types they belong to and the interfaces they implement. By using a custom type membership class, you can make objects belong (or not belong) to unions or interfaces, depending on the API version.)

Once those integrations are set up, you're ready to write a changeset and start releasing API versions!

Controller Setup Copy Chapter

Additionally, your controller must pass context[:changeset_version] when running queries. To provide this, update your controller:

class GraphqlController < ApplicationController
  def execute
    context = {
      # ...
      changeset_version: request.headers["API-Version"], # <- Your header here. Choose something for API clients to pass.
    }
    result = MyAppSchema.execute(..., context: context)
    # ...
  end
end

In the example above, API-Version: ... will be parsed from the incoming request and used as context[:changeset_version].

If context[:changeset_version] is nil, then no changesets will apply to that request.

Now that Changesets are installed, read on to define some changesets.

Guides Changesets Releases (`guides/changesets/releases.md`) Copy Section

Releasing Changesets

To be available to clients, Changesets added to the schema with use GraphQL::Enterprise::Changeset::Release changesets_dir: "...":

class MyAppSchema < GraphQL::Schema
  # Add this before root types so that newly-added types are also added to the schema
  use GraphQL::Enterprise::Changeset::Release, changesets_dir: "app/graphql/changesets"

  query(...)
  mutation(...)
  subscription(...)
end

This attaches each Changeset defined in app/graphql/changesets/*.rb to the schema. (It assumes Rails conventions, where an underscored file like app/graphql/changesets/add_some_feature.rb contains a class like Changesets::AddSomeFeature.)

Warning:

Add GraphQL::Enterprise::Changeset::Release before hooking up your root query(...), mutation(...), and subscription(...) types. Otherwise, the schema may not find links to types in new schema versions.

Alternatively, Changesets can be explicitly attached using changesets: [...], for example:

class MyAppSchema < GraphQL::Schema
  use GraphQL::Enterprise::Changeset::Release, changesets: [
    Changesets::DeprecateRecipeFlag,
    Changesets::RemoveRecipeFlag,
  ]
  # ...
end

Only changesets in the directory (or in the array) will be shown to clients. The release ... configuration in the changeset will be compared to context[:changeset_version] to determine if the changeset applies to the current request.

Inspecting Releases Copy Chapter

To preview releases, you can create schema dumps by passing context: { changeset_version: ... } to Schema.to_definition.

For example, to see how the schema looks with API-Version: 2021-06-01:

schema_sdl = MyAppSchema.to_definition(context: { changeset_version: "2021-06-01"})
# The GraphQL schema definition for the schema at version "2021-06-01":
puts schema_sdl

To make sure schema versions don't change unexpectedly, use the techniques described in the Schema structure guide.

Introspection Methods Copy Section

You can also inspect a schema's changesets programmatically. GraphQL::Enterprise adds a Schema.changesets method which returns a Set of changeset classes:

MySchema.changesets
# #<Set: {AddNewFeature, RemoveOldFeature}>

Additionally, each changeset has a .changes method describing its modifications:

AddNewFeature.changes
# [
#   #<GraphQL::Enterprise::Changeset::Change: ...>,
#   #<GraphQL::Enterprise::Changeset::Change: ...>,
#   #<GraphQL::Enterprise::Changeset::Change: ...>,
#   ...
# ]

Each Change object responds to:

• .member, the part of the schema that was modified
• .type, the kind of modification (:addition when something new is added, :removal when a member is removed or replaced with a new definition)

Guides Dataloader Adopting (`guides/dataloader/adopting.md`) Copy Section

Dataloader vs. GraphQL-Batch

GraphQL::Dataloader solves the same problem as GraphQL::Batch. There are a few major differences between the modules:

• Concurrency Primitive: GraphQL-Batch uses Promises from promise.rb; GraphQL::Dataloader uses Ruby's Fiber API. These primitives dictate how batch loading code is written (see below for comparisons).
• Maturity: Frankly, GraphQL-Batch is about as old as GraphQL-Ruby, and it's been in production at Shopify, GitHub, and others for many years. GraphQL::Dataloader is new, and although Ruby has supported Fibers since 1.9, they still aren't widely used.
• Scope: It's not currently possible to use GraphQL::Dataloader outside GraphQL.

The incentive in writing GraphQL::Dataloader was to leverage Fiber's ability to transparently pause and resume work, which removes the need for Promises (and removes the resulting complexity in the code). Additionally, GraphQL::Dataloader should eventually support Ruby 3.0's Fiber.scheduler API, which runs I/O in the background by default.

Comparison: Fetching a single object Copy Chapter

In this example, a single object is batch-loaded to satisfy a GraphQL field.

• With GraphQL-Batch, you call a loader, which returns a Promise:

  ruby Copy

  record_promise = Loaders::Record.load(1)

  Then, under the hood, GraphQL-Ruby manages the promise (using its lazy_resolve feature, upstreamed from GraphQL-Batch many years ago). GraphQL-Ruby will call .sync on it when no further execution is possible; promise.rb implements Promise#sync to execute the pending work.

• With GraphQL::Dataloader, you get a source, then call .load on it, which may pause the current Fiber, but it returns the requested object.

  ruby Copy

  dataloader.with(Sources::Record).load(1)

  Since the requested object is (eventually) returned from .load, Nothing else is required.

Comparison: Fetching objects in sequence (dependent) Copy Chapter

In this example, one object is loaded, then another object is loaded based on the first one.

• With GraphQL-Batch, .then { ... } is used to join dependent code blocks:

  ruby Copy

  Loaders::Record.load(1).then do |record|
    Loaders::OtherRecord.load(record.other_record_id)
  end

  That call returns a Promise, which is stored by GraphQL-Ruby, and finally .synced.

• With GraphQL-Dataloader, .load(...) returns the requested object (after a potential Fiber pause), so no other method calls are necessary:

  ruby Copy

  record = dataloader.with(Sources::Record).load(1)
  dataloader.with(Sources::OtherRecord).load(record.other_record_id)

Comparison: Fetching objects concurrently (independent) Copy Chapter

Sometimes, you need multiple independent records to perform a calculation. Each record is loaded, then they're combined in some bit of work.

• With GraphQL-Batch, Promise.all(...) is used to wait for several pending loads:

  ruby Copy

  promise_1 = Loaders::Record.load(1)
  promise_2 = Loaders::OtherRecord.load(2)
  Promise.all([promise_1, promise_2]).then do |record, other_record|
    do_something(record, other_record)
  end

  If the objects are loaded from the same loader, then .load_many also works:

  ruby Copy

  Loaders::Record.load_many([1, 2]).then do |record, other_record|
    do_something(record, other_record)
  end

• With GraphQL::Dataloader, each request is registered with .request(...) (which never pauses the Fiber), then data is loaded with .load (which will pause the Fiber as needed):

  ruby Copy

  # first, make some requests
  request_1 = dataloader.with(Sources::Record).request(1)
  request_2 = dataloader.with(Sources::OtherRecord).request(2)
  # then, load the objects and do something
  record = request_1.load
  other_record = request_2.load
  do_something(record, other_record)

  If the objects come from the same Source, then .load_all will return the objects directly:

  ruby Copy

  record, other_record = dataloader.with(Sources::Record).load_all([1, 2])
  do_something(record, other_record)

Guides Dataloader Async Dataloader (`guides/dataloader/async_dataloader.md`) Copy Section

Async Source Execution

AsyncDataloader will run GraphQL::Dataloader::Source#fetch calls in parallel, so that external service calls (like database queries or network calls) don't have to wait in a queue.

To use AsyncDataloader, hook it up in your schema instead of GraphQL::Dataloader:

- use GraphQL::Dataloader
+ use GraphQL::Dataloader::AsyncDataloader

Also, add the async gem to your project, for example:

bundle add async

Now, GraphQL::Dataloader::AsyncDataloader will create Async::Task instances instead of plain Fibers and the async gem will manage parallelism.

For a demonstration of this behavior, see: https://github.com/rmosolgo/rails-graphql-async-demo

You can also implement manual parallelism using dataloader.yield.

Rails Copy Chapter

For Rails, you'll need Rails 7.1, which properly supports fiber-based concurrency, and you'll also want to configure Rails to use Fibers for isolation:

class Application < Rails::Application
  # ...
  config.active_support.isolation_level = :fiber
end

ActiveRecord Connections Copy Section

You can use Dataloader's Fiber lifecycle hooks to improve ActiveRecord connection handling:

• In Rails < 7.2, connections are not reused when a Fiber exits; instead, they're only reused when a request or background job finishes. You can add manual release_connection calls to improve this.
• With isolation_level = :fiber, new Fibers don't inherit connected_to ... settings from their parent fibers.

Altogether, it can be improved like this:

def get_fiber_variables
  vars = super
  # Collect the current connection config to pass on:
  vars[:connected_to] = {
    role: ActiveRecord::Base.current_role,
    shard: ActiveRecord::Base.current_shard,
    prevent_writes: ActiveRecord::Base.current_preventing_writes
  }
  vars
end

def set_fiber_variables(vars)
  connection_config = vars.delete(:connected_to)
  # Reset connection config from the parent fiber:
  ActiveRecord::Base.connecting_to(**connection_config)
  super(vars)
end

def cleanup_fiber
  super
  # Release the current connection
  ActiveRecord::Base.connection_pool.release_connection
end

Modify the example according to your database configuration and abstract class hierarchy.

Other Options Copy Chapter

You can also manually implement parallelism with Dataloader. See the Dataloader Parallelism guide for details.

Guides Dataloader Dataloader (`guides/dataloader/dataloader.md`) Copy Section

Dataloader

GraphQL::Dataloader instances are created for each query (or multiplex) and they:

• Cache Source instances for the duration of GraphQL execution
• Run pending Fibers to resolve data requirements and continue GraphQL execution

During a query, you can access the dataloader instance with:

• GraphQL::Query::Context#dataloader (context.dataloader, anywhere that query context is available)
• GraphQL::Schema::Object#dataloader (dataloader inside a resolver method)
• GraphQL::Schema::Resolver#dataloader (dataloader inside def resolve of a Resolver, Mutation, or Subscription class.)

Fiber Lifecycle Hooks Copy Chapter

Under the hood, Dataloader creates Fibers as-needed and uses them to run GraphQL and load data from Source classes. You can hook into these Fibers through several lifecycle hooks. To implement these hooks, create a custom subclass and provide new implementation for these methods:

class MyDataloader < GraphQL::Dataloader # or GraphQL::Dataloader::AsyncDataloader
  # ...
end

Then, use your customized dataloader instead of the built-in one:

class MySchema < GraphQL::Schema
-   use GraphQL::Dataloader
+   use MyDataloader
  end

• GraphQL::Dataloader#get_fiber_variables is called before creating a Fiber. By default, it returns a hash containing the parent Fiber's variables (from Thread.current[...]). You can add to this hash in your own implementation of this method.
• GraphQL::Dataloader#set_fiber_variables is called inside the new Fiber. It's passed the hash returned from get_fiber_variables. You can use this method to initialize "global" state inside the new Fiber.
• GraphQL::Dataloader#cleanup_fiber is called just before a Dataloader Fiber exits. You can use this methods to teardown any state that you prepared in set_fiber_variables.

Guides Dataloader Parallelism (`guides/dataloader/parallelism.md`) Copy Section

Manual Parallelism

You can coordinate with GraphQL::Dataloader to run tasks in the background. To do this, call dataloader.yield inside Source#fetch after kicking off your task. For example:

def fetch(ids)
  # somehow queue up a background query,
  # see examples below
  future_result = async_query_for(ids)
  # return control to the dataloader
  dataloader.yield
  # dataloader will come back here
  # after calling other sources,
  # now wait for the value
  future_result.value
end

Alternatively, you can use AsyncDataloader to automatically background I/O inside Source#fetch calls.

Example: Rails load_async Copy Chapter

You can use Rails's load_async method to load ActiveRecord::Relations in the background. For example:

class Sources::AsyncRelationSource < GraphQL::Dataloader::Source
  def fetch(relations)
    relations.each(&:load_async) # start loading them in the background
    dataloader.yield # hand back to GraphQL::Dataloader
    relations.each(&:load) # now, wait for the result, returning the now-loaded relation
  end
end

You could call that source from a GraphQL field method:

field :direct_reports, [Person]

def direct_reports
  # prepare an ActiveRecord::Relation:
  direct_reports = Person.where(manager: object)
  # pass it off to the source:
  dataloader
    .with(Sources::AsyncRelationSource)
    .load(direct_reports)
end

Example: Rails async calculations Copy Chapter

In a Dataloader source, you can run Rails async calculations in the background while other work continues. For example:

class Sources::DirectReportsCount < GraphQL::Dataloader::Source
  def fetch(users)
    # Start the queries in the background:
    promises = users.map { |u| u.direct_reports.async_count }
    # Return to GraphQL::Dataloader:
    dataloader.yield
    # Now return the results, waiting if necessary:
    promises.map(&:value)
  end
end

Which could be used in a GraphQL field:

field :direct_reports_count, Int

def direct_reports_count
  dataloader.with(Sources::DirectReportsCount).load(object)
end

Example: Concurrent::Future Copy Chapter

You could use concurrent-ruby to put work in a background thread. For example, using Concurrent::Future:

class Sources::ExternalDataSource < GraphQL::Dataloader::Source
  def fetch(urls)
    # Start some I/O-intensive work:
    futures = urls.map do |url|
      Concurrent::Future.execute {
        # Somehow fetch and parse data:
        get_remote_json(url)
      }
    end
    # Yield back to GraphQL::Dataloader:
    dataloader.yield
    # Dataloader has done what it can,
    # so now return the value, waiting if necessary:
    futures.map(&:value)
  end
end

Guides Dataloader Sources (`guides/dataloader/sources.md`) Copy Section

Sources

Sources are what GraphQL::Dataloader uses to fetch data from external services.

Source Concepts Copy Chapter

Sources are classes that inherit from GraphQL::Dataloader::Source. A Source must implement def fetch(keys) to return a list of objects, one for each of the given keys. A source may implement def initialize(...) to accept other batching parameters.

Sources will receive two kinds of inputs from GraphQL::Dataloader:

• keys, which correspond to objects requested by the application.

  Keys are passed to def fetch(keys), which must return an object (or nil) for each of keys, in the same order as keys.

  Under the hood, each Source instance maintains a key => object cache.

• batch parameters, which are the basis of batched groups. For example, if you're loading records from different database tables, the table name would be a batch parameter.

  Batch parameters are given to dataloader.with(source_class, *batch_parameters), and the default is no batch parameters. When you define a source, you should add the batch parameters to def initialize(...) and store them in instance variables.

  (dataloader.with(source_class, *batch_parameters) returns an instance of source_class with the given batch parameters -- but it might be an instance which was cached by dataloader.)

  Additionally, batch parameters are used to de-duplicate Source initializations during a query run. .with(...) calls that have the same batch parameters will use the same Source instance under the hood. To customize how Sources are de-duplicated, see GraphQL::Dataloader::Source.batch_key_for.

Example: Loading Strings from Redis by Key Copy Chapter

The simplest source might fetch values based on their keys. For example:

# app/graphql/sources/redis_string.rb
class Sources::RedisString < GraphQL::Dataloader::Source
  REDIS = Redis.new
  def fetch(keys)
    # Redis's `mget` will return a value for each key with a `nil` for any not-found key.
    REDIS.mget(*keys)
  end
end

This loader could be used in GraphQL like this:

some_string = dataloader.with(Sources::RedisString).load("some_key")

Calls to .load(key) will be batched, and when GraphQL::Dataloader can't go any further, it will dispatch a call to def fetch(keys) above.

Example: Loading ActiveRecord Objects by ID Copy Chapter

To fetch ActiveRecord objects by ID, the source should also accept the model class as a batching parameter. For example:

# app/graphql/sources/active_record_object.rb
class Sources::ActiveRecordObject < GraphQL::Dataloader::Source
  def initialize(model_class)
    @model_class = model_class
  end

  def fetch(ids)
    records = @model_class.where(id: ids)
    # return a list with `nil` for any ID that wasn't found
    ids.map { |id| records.find { |r| r.id == id.to_i } }
  end
end

This source could be used for any model_class, for example:

author = dataloader.with(Sources::ActiveRecordObject, ::User).load(1)
post = dataloader.with(Sources::ActiveRecordObject, ::Post).load(1)

Example: Batched Calculations Copy Chapter

Besides fetching objects, Sources can return values from batched calculations. For example, a system could batch up checks for who a user follows:

# for a given user, batch checks to see whether this user follows another user.
# (The default `user.followings.where(followed_user_id: followed).exists?` would cause N+1 queries.)
class Sources::UserFollowingExists < GraphQL::Dataloader::Source
  def initialize(user)
    @user = user
  end

  def fetch(handles)
    # Prepare a `SELECT id FROM users WHERE handle IN(...)` statement
    user_ids = ::User.where(handle: handles).select(:id)
    # And use it to filter this user's followings:
    followings = @user.followings.where(followed_user_id: user_ids)
    # Now, for followings that _actually_ hit a user, get the handles for those users:
    followed_users = ::User.where(id: followings.select(:followed_user_id))
    # Finally, return a result set, with one entry (true or false) for each of the given `handles`
    handles.map { |h| !!followed_users.find { |u| u.handle == h }}
  end
end

It could be used like this:

is_following = dataloader.with(Sources::UserFollowingExists, context[:viewer]).load(handle)

After all requests were batched, #fetch will return a Boolean result to is_following.

Example: Loading in a background thread Copy Chapter

Inside Source#fetch(keys), you can call dataloader.yield to return control to the Dataloader. This way, it will proceed loading other Sources (if there are any), then return the source that yielded.

A simple example, spinning up a new Thread:

def fetch(keys)
  # spin up some work in a background thread
  thread = Thread.new {
    fetch_external_data(keys)
  }
  # return control to the dataloader
  dataloader.yield
  # at this point,
  # the dataloader has tried everything else and come back to this source,
  # so block if necessary:
  thread.value
end

See the parallelism guide for details about this approach.

Filling the Dataloader Cache Copy Chapter

If you load records from the database, you can use them to populate a source's cache by using Dataloader::Source#merge. For example:

# Build a `{ key => value }` map to populate the cache
comments_by_id = post.comments.each_with_object({}) { |comment, hash| hash[comment.id] = comment }
# Merge the map into the source's cache
dataloader.with(Sources::ActiveRecordObject, Comment).merge(comments_by_id)

After that, any calls to .load(id) will use those already-loaded records if they're available.

De-duplicating equivalent objects Copy Chapter

Sometimes, different objects in the application should load the same object from fetch. You can customize this behavior by implementing def result_key_for(key) in your application. For example, to map records from your ORM to their database ID:

# Load the `created_by` person for a record from our database
class CreatedBySource < GraphQL::Dataloader::Source
  def result_key_for(key)
    key.id # Use the record's ID to deduplicate different `.load` calls
  end

  # Fetch a `person` for each of `records`, based on their created_by_id
  def fetch(records)
    PersonService.find_each(records.map(&:created_by_id))
  end
end

In this case, records will include the first object for each unique record.id -- subsequent records with the same .id will be assumed to be duplicates. Under the hood, the Source will cache the result based on the record's id.

Alternatively, you could use this to make the Source retain each incoming object, even when they would otherwise be treated as duplicates. (This would come in handy when you need def fetch to mutate each object). For example, to treat every incoming object as distinct:

def result_key_for(record)
  record.object_id # even if the records are equivalent, handle each distinct Ruby object separately
end

Guides Dataloader Testing (`guides/dataloader/testing.md`) Copy Section

Testing

There are a few techniques for testing your GraphQL::Dataloader setup.

Integration Tests Copy Chapter

One important feature of Dataloader is how it manages database access while GraphQL runs queries. You can test that by listening for database queries while running queries, for example, with ActiveRecord:

def test_active_record_queries_are_batched_and_cached
  # set up a listener function
  database_queries = 0
  callback = lambda {|_name, _started, _finished, _unique_id, _payload| database_queries += 1 }

  query_str = <<-GRAPHQL
  {
    a1: author(id: 1) { name }
    a2: author(id: 2) { name }
    b1: book(id: 1) { author { name } }
    b2: book(id: 2) { author { name } }
  }
  GRAPHQL

  # Run the query with the listener
  ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
    MySchema.execute(query_str)
  end

  # One query for authors, one query for books
  assert_equal 2, database_queries
end

You could also make specific assertions on the queries that are run (see the sql.active_record docs). For other frameworks and databases, check your ORM or library for instrumentation options.

Testing Dataloader Sources Copy Chapter

You can also test Dataloader behavior outside of GraphQL using GraphQL::Dataloader.with_dataloading. For example, let's say you have a Sources::ActiveRecord source defined like so:

module Sources
  class User < GraphQL::Dataloader::Source
    def fetch(ids)
      records = User.where(id: ids)
      # return a list with `nil` for any ID that wasn't found, so the shape matches
      ids.map { |id| records.find { |r| r.id == id.to_i } }
    end
  end
end

You can test it like so:

def test_it_fetches_objects_by_id
  user_1, user_2, user_3 = 3.times.map { User.create! }

  database_queries = 0
  callback = lambda {|_name, _started, _finished, _unique_id, _payload| database_queries += 1 }

  ActiveSupport::Notifications.subscribed(callback, "sql.active_record") do
    GraphQL::Dataloader.with_dataloading do |dataloader|
      req1 = dataloader.with(Sources::ActiveRecord).request(user_1.id)
      req2 = dataloader.with(Sources::ActiveRecord).request(user_2.id)
      req3 = dataloader.with(Sources::ActiveRecord).request(user_3.id)
      req4 = dataloader.with(Sources::ActiveRecord).request(-1)

      # Validate source's matching up of records
      expect(req1.load).to eq(user_1)
      expect(req2.load).to eq(user_2)
      expect(req3.load).to eq(user_3)
      expect(req4.load).to be_nil
    end
  end

  assert_equal 1, database_queries, "All users were looked up at once"
end

Guides Defer Graphiql (`guides/defer/graphiql.md`) Copy Section

Use with GraphiQL

You can use @defer and @stream with GraphiQL, an in-browser IDE.

Incremental responses Copy Chapter

If you're using the proposed incremental: ... response syntax (proposal, Ruby support), you'll need a custom "fetcher" function to handle the incremental: ... part of the response. For example:

import { meros } from "meros"; // for handling multipart responses

const customFetcher = async function* (graphqlParams, fetcherOpts) {
  // Make the initial fetch
  var result = await fetch("/graphql", {
    method: "POST",
    body: JSON.stringify(graphqlParams),
    headers: {
      'content-type': 'application/json',
    }
  }).then((r) => {
    // Use meros to turn multipart responses into streams
    return meros(r, { multiple: true })
  })

  if (!isAsyncIterable(result)) {
    // Return plain responses as promises
    return result.json()
  } else {
    // Handle multipart responses one chunk at a time
    for await (const chunk of result) {
      yield chunk.map(part => {
        // Move the incremental part of the response into top-level
        // This assumes there's only one `incremental` entry
        // which is currently true for GraphQL-Pro's @defer implementation
        var newJson = {...part.body}
        if (newJson.incremental) {
          newJson.data = newJson.incremental[0].data
          newJson.path = newJson.incremental[0].path
          delete newJson.incremental
        }
        return newJson
      });
    }
  }
}

// Helper for checking for a multipart response:
function isAsyncIterable(input) {
  return (
      typeof input === "object" &&
      input !== null &&
      (
        input[Symbol.toStringTag] === "AsyncGenerator" ||
        (Symbol.asyncIterator && Symbol.asyncIterator in input)
      )
    );
}

Hopefully a new GraphiQL version will support this out of the box; follow the issue on GitHub.

Guides Defer Setup (`guides/defer/setup.md`) Copy Section

Server Setup

Before using @defer in queries, you have to:

• Update graphql and graphql-pro gems
• Add @defer to your GraphQL schema
• Update your HTTP handlers (eg, Rails controllers) to send streaming responses
• Optionally, customize @defer to work with GraphQL-Batch

You can also see a full Rails & Apollo-Client demo.

Updating the gems Copy Chapter

GraphQL-Ruby 1.9+ and GraphQL-Pro 1.10+ are required:

gem "graphql", "~>1.9"
gem "graphql-pro", "~>1.10"

And then install them:

$ bundle update graphql graphql-pro

Adding `@defer` to your schema Copy Chapter

Then, add GraphQL::Pro::Defer to your schema as a plugin:

class MySchema < GraphQL::Schema
  use GraphQL::Pro::Defer
end

This will:

• Attach a custom directive called @defer
• Add instrumentation to queries to track deferred work and execute it later

Sending streaming responses Copy Chapter

Many web frameworks have support for streaming responses, for example:

• Rails has ActionController::Live
• Sinatra has Sinatra::Streaming
• Hanami::Controller can stream responses

See below for how to integrate GraphQL's deferred patches with a streaming response API.

To investigate support with a web framework, please open an issue or email [email protected].

Checking for deferrals Copy Section

When a query has any @defered fields, you can check for context[:defer]:

if context[:defer]
  # some fields were `@defer`ed
else
  # normal GraphQL, no `@defer`
end

Working with deferrals Copy Section

To handle deferrals, you can enumerate over context[:defer], for example:

context[:defer].each do |deferral|
  # do something with the `deferral`, eg
  # stream_to_client(deferral.to_h)
end

The initial result is also present in the deferrals, so you can treat it just like a patch.

Each deferred patch has a few methods for building a response:

• .to_h returns a hash with path:, data:, and/or errors:. (There is no path: for the root result.)
• .to_http_multipart(incremental: true) returns a string which works with Apollo client's @defer support. (Use incremental: true to format patches for the forthcoming spec.)
• .path returns the path to this patch in the response
• .data returns successfully-resolved results of the patch
• .errors returns an array of errors, if there were any

Calling .data or .errors on a deferral will resume GraphQL execution until the patch is complete.

Example: Rails with Apollo Client Copy Section

In this example, a Rails controller will stream HTTP Multipart patches to the client, in Apollo Client's supported format.

class GraphqlController < ApplicationController
  # Support `response.stream` below:
  include ActionController::Live

  def execute
    # ...
    result = MySchema.execute(query, variables: variables, context: context, operation_name: operation_name)

    # Check if this is a deferred query:
    if (deferred = result.context[:defer])
      # Required for Rack 2.2+, see https://github.com/rack/rack/issues/1619
      response.headers['Last-Modified'] = Time.now.httpdate
      # Use built-in `stream_http_multipart` with Apollo-Client & ActionController::Live
      deferred.stream_http_multipart(response, incremental: true)
    else
      # Return a plain, non-deferred result
      render json: result
    end
  ensure
    # Always make sure to close the stream
    response.stream.close
  end
end

You can also investigate a full Rails & Apollo-Client demo

With GraphQL-Batch Copy Chapter

GraphQL-Batch is a third-party data loading library that wraps GraphQL-Ruby execution. Deferred resolution happens outside the normal execution flow, so to work with GraphQL-Batch, you have to customize GraphQL::Pro::Defer a bit. Also, you'll need GraphQL-Pro v1.24.6 or later. Here's a custom Defer implementation:

# app/graphql/directives/defer.rb
module Directives
  # Modify the library's `@defer` implementation to work with GraphQL-Batch
  class Defer < GraphQL::Pro::Defer
    def self.resolve(obj, arguments, context, &block)
      # While the query is running, store the batch executor to re-use later
      context[:graphql_batch_executor] ||= GraphQL::Batch::Executor.current
      super
    end

    class Deferral < GraphQL::Pro::Defer::Deferral
      def resolve
        # Before calling the deferred execution,
        # set GraphQL-Batch back up:
        prev_executor = GraphQL::Batch::Executor.current
        GraphQL::Batch::Executor.current ||= @context[:graphql_batch_executor]
        super
      ensure
        # Clean up afterward:
        GraphQL::Batch::Executor.current = prev_executor
      end
    end
  end
end

And update your schema to use your custom defer implementation:

# Use our GraphQL-Batch-compatible defer:
use Directives::Defer

Next Steps Copy Chapter

Read about client usage of @defer.

Guides Defer Stream (`guides/defer/stream.md`) Copy Section

Stream

@stream works very much like @defer, except it only applies to list fields. When a field has @stream and it returns a list, then each item in the list is returned to the client as a patch. @stream is described in a proposal to the GraphQL specification.

Note: @stream was added in GraphQL-Pro 1.21.0 and requires GraphQL-Ruby 1.13.6+.

Installation Copy Chapter

To support @stream in your schema, add it with use GraphQL::Pro::Stream:

class MySchema < GraphQL::Schema
  # ...
  use GraphQL::Pro::Stream
end

Additionally, you should update your controller to handle deferred parts of the response. See the @defer setup guide for details. (@stream uses the same deferral pipeline as @defer, so the same setup instructions apply.)

Usage Copy Chapter

After that, you can include @stream in your queries, for example:

{
  # Send each movie in its own patch:
  nowPlaying @stream {
    title
    director { name }
  }
}

If @stream is applied to non-list fields, it's ignored.

@stream supports several arguments:

• if: Boolean = true: when false, the list is not streamed. Instead, all items are returned synchronously.
• label: String: if present, the given string is returned in patches as "label": "..."
• initialCount: Int = 0: this number of list items are returned synchronously. (If the list is shorter than initialCount, then the whole list is returned synchronously.)

Guides Defer Usage (`guides/defer/usage.md`) Copy Section

Usage

@defer is a GraphQL directive which instructs the server to execute the field in a special way:

query GetPlayerInfo($handle: String!){
  player(handle: $handle) {
    name
    # Send this field later, to avoid slowing down the initial response:
    topScore(from: 2000, to: 2020) @defer
  }
}

The directives @skip and @include are built into any GraphQL server and client, but @defer requires special attention.

Apollo-Client currently supports the @defer directive.

@defer also accepts a label: option which will be included in outgoing patches when it's present in the query (eg, @defer(label: "patch1")).

Want to use @defer with another client? Please open an issue or email [email protected] and we'll dig in!

Next Steps Copy Chapter

Set up your server to support @defer.

Guides Development Development (`guides/development/development.md`) Copy Section

Development

So, you want to hack on GraphQL Ruby! Here are some tips for getting started.

• Setup your development environment
• Run the tests to verify your setup
• Debug with pry
• Run the benchmarks to test performance in your environment
• Coding guidelines for working on your contribution
• Special tools for building the lexer and parser
• Building and publishing the GraphQL Ruby website
• Versioning describes how changes are managed and released
• Releasing Gem versions

Setup Copy Chapter

Get your own copy of graphql-ruby by forking rmosolgo/graphql-ruby on GitHub and cloning your fork.

Then, install the dependencies:

• Install SQLite3 and MongoDB (eg, brew install sqlite && brew tap mongodb/brew && brew install mongodb-community)
• bundle install
• rake compile # If you get warnings at this step, you can ignore them.
• Optional: Ragel is required to build the lexer

Running the Tests Copy Chapter

Unit tests Copy Section

You can run the tests with

bundle exec rake        # tests & Rubocop
bundle exec rake test   # tests only

You can run a specific file with TEST=:

bundle exec rake test TEST=spec/graphql/query_spec.rb
# run tests in `query_spec.rb` only

You can focus on a specific example with focus:

focus
it "does something cool" do
  # ...
end

Then, only focused tests will run:

bundle exec rake test
# only the focused test will be run

(This is provided by minitest-focus.)

Integration tests Copy Section

You need to pick a specific gemfile from gemfiles/ to run integration tests. For example:

BUNDLE_GEMFILE=gemfiles/rails_6.1.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails_6.1.gemfile bundle exec rake test TEST=spec/integration/rails/graphql/relay/array_connection_spec.rb

GraphQL-CParser tests Copy Section

To test the graphql_cparser gem, you have to build the binary first:

bundle exec rake build_ext

Then, run the test suite with GRAPHQL_CPARSER=1:

GRAPHQL_CPARSER=1 bundle exec rake test

(Add TEST= to pick a certain file.)

Other tests Copy Section

There are system tests for checking ActionCable behavior, use:

bundle exec rake test:system

And JavaScript tests:

bundle exec rake test:js

Gemfiles, Gemfiles, Gemfiles Copy Chapter

graphql-ruby has several gemfiles to ensure support for various Rails versions. You can specify a gemfile with BUNDLE_GEMFILE, eg:

BUNDLE_GEMFILE=gemfiles/rails_5.gemfile bundle exec rake test

Debugging with Pry Copy Chapter

pry is included with GraphQL-Ruby's development setup to help with debugging.

To pause execution in Ruby code, add:

binding.pry

Then, the program will pause and your terminal will become a Ruby REPL. Feel free to use pry in your development process!

Running the Benchmarks Copy Chapter

This project includes some Rake tasks to record benchmarks:

$ bundle exec rake -T | grep bench:
rake bench:profile         # Generate a profile of the introspection query
rake bench:query           # Benchmark the introspection query
rake bench:validate        # Benchmark validation of several queries

You can save results by sending the output into a file:

$ bundle exec rake bench:validate > before.txt
$ cat before.txt
# ...
# --> benchmark output here

If you want to check performance, create a baseline by running these tasks before your changes. Then, make your changes and run the tasks again and compare your results.

Keep these points in mind when using benchmarks:

• The results are hardware-specific: computers with different hardware will have different results. So don't compare your results to results from other computers.
• The results are environment-specific: CPU and memory availability are affected by other processes on your computer. So try to create similar environments for your before-and-after testing.

Coding Guidelines Copy Chapter

GraphQL-Ruby uses a thorough test suite to make sure things work reliably day-after-day. Please include tests that describe your changes, for example:

• If you contribute a bug fix, include a test for the code that was broken (and is now fixed)
• If you contribute a feature, include tests for all intended uses of that feature
• If you modify existing behavior, update the tests to cover all intended behaviors for that code

Don't fret about coding style or organization. There's a minimal Rubocop config in .rubocop.yml which runs during CI. You can run it manually with bundle exec rake rubocop.

Website Copy Chapter

To update the website, update the .md files in guides/.

Install the optional documentation dependencies and build the site locally:

BUNDLE_WITH=docs bundle install
bundle exec rake docs:build
bundle exec rake docs:rdoc:serve

Then visit http://127.0.0.1:8808. Run the documentation checks before submitting a change:

bundle exec rake docs:check
bundle exec rake docs:build_twice

See the documentation maintenance guide for API links, GraphQL code blocks, redirects, and release documentation.

API Docs Copy Section

The GraphQL-Ruby website has a rendered version of each published gem's API docs. Generate a local copy with:

$ bundle exec rake "docs:rdoc:build_version[1.8.0]"

The output is written to tmp/rdoc-api/1.8.0/; the release workflow publishes it under /api-doc/1.8.0/ while preserving older versions.

Versioning Copy Chapter

GraphQL-Ruby does not attempt to deliver "semantic versioning" for the reasons described in jashkenas'
s post, "Why Semantic Versioning Isn't". Instead, the following scheme is used as a guideline:

• Version numbers consist of three parts, MAJOR.MINOR.PATCH
• PATCH version indicates bug fixes or small features for specific use cases. Ideally, you can upgrade patch versions with only a quick skim of the changelog.
• MINOR version indicates significant additions, internal refactors, or small breaking changes. When upgrading a minor version, check the changelog for any new features or breaking changes which apply to your system. The changelog will always include an upgrade path for any breaking changes. Minor versions may also include deprecation warnings to warn about upcoming breaking changes.
• MAJOR version indicates significant breaking changes. Do not expect code to run without some modification, especially if the code yielded deprecation warnings.

This policy is inspired by the Ruby 2.1.0+ version policy.

Pull requests and issues may be tagged with a GitHub milestone to denote when they'll be released.

The changelog should always contain accurate and thorough information so that users can upgrade. If you have trouble upgrading based on the changelog, please open an issue on GitHub.

Releasing Copy Chapter

GraphQL-Ruby doesn't have a strict release schedule. If you think it should, consider opening an issue to share your thoughts.

To cut a release:

• Update CHANGELOG.md for the new version:
  • Add a new heading for the new version, and paste the four categories of changes into the new section
  • Open the GitHub milestone corresponding to the new version
  • Check each pull request and put it in the category (or categories) that it belongs in
    • If a change affects the default behavior of GraphQL-Ruby in a disruptive way, add it to ## Breaking Changes and include migration notes if possible
    • Include the PR number beside the change description for future reference
• Update lib/graphql/version.rb with the new version number
• Commit changes to master
• Push changes to GitHub: git push origin master. GitHub Actions will update the website.
• Release to RubyGems: bundle exec rake release. This will also push the tag to GitHub which will kick off a GitHub Actions job to update the API docs.
• Celebrate 🎊 !

Guides Development Documentation Maintenance (`guides/development/documentation_maintenance.md`) Copy Section

Documentation maintenance

GraphQL-Ruby documentation is generated with RDoc and the Aliki generator. API comments live beside the Ruby code, while tutorials and cross-cutting explanations remain Markdown pages in guides/.

Install the optional documentation dependencies and build a local site with:

BUNDLE_WITH=docs bundle install
bundle exec rake docs:build

The generated site is written to tmp/rdoc-site. To preview it, run bundle exec rake docs:rdoc:serve and open http://127.0.0.1:8808.

When adding or moving a guide, update docs/guide_metadata.yml; it controls sidebar order and the GraphQL-Pro and GraphQL-Enterprise callouts.

Run the documentation checks before submitting a change:

bundle exec rake docs:check
bundle exec rake docs:build_twice

Use rdoc-ref:GraphQL::Schema#execute (or the corresponding class-method form) for links from comments and guides. Add a short API comment when a public method is missing from the generated index. Dynamic methods should use RDoc directives such as :method: and :call-seq: rather than introducing new YARD tags.

Use a fenced graphql block for GraphQL examples:

```graphql
query Viewer {
  viewer { id }
}
```

When a page or API moves, add an entry to docs/redirects.yml so the old URL remains usable. Run bundle exec ruby tool/docs/link_checker.rb --root tmp/rdoc-site --strict to verify the redirect and its fragment.

Release builds use bundle exec rake "docs:rdoc:build_version[VERSION]" to generate a versioned API site under tmp/rdoc-api/VERSION. The publish workflow copies that directory into gh-pages/api-doc/VERSION without removing older versions.

Guides Development Faq (`guides/development/faq.md`) Copy Section

FAQ

Returning Route URLs

With GraphQL there is less of a need to include resource URLs to other REST resources, however sometimes you want to use Rails routing to include a URL as one of your fields. A common use case would be to build HTML format URLs to render a link in your React UI. In that case you can pass the request to your context, so that the helpers are able to build full URLs based on the incoming host, port and protocol.

Example Copy Chapter

class Types::UserType < Types::BaseObject
  include ActionController::UrlFor
  include Rails.application.routes.url_helpers
  # Needed by ActionController::UrlFor to extract the host, port, protocol etc. from the current request
  def request
    context[:request]
  end
  # Needed by Rails.application.routes.url_helpers, it will then use the url_options defined by ActionController::UrlFor
  def default_url_options
    {}
  end
  
  field :profile_url, String, null: false
  def profile_url
    user_url(object)
  end
end

# In your GraphQL controller, add the request to `context`:
MySchema.execute(
  params[:query],
  variables: params[:variables],
  context: {
    request: request
  },
)

Returning ActiveStorage blob URLs

If you are using ActiveStorage and need to return a URL to an attachment blob, you will find that using Rails.application.routes.url_helpers.rails_blob_url alone will throw an exception since Rails won't know what host, port or protocol to use in it.
You can include ActiveStorage::SetCurrent in your GraphQL controller to pass on this information into your resolvers.

Example

class GraphqlController < ApplicationController
  include ActiveStorage::SetCurrent
  ...
end

class Types::UserType < Types::BaseObject
  field :picture_url, String, null: false
  def picture_url
    Rails.application.routes.url_helpers.rails_blob_url(
      object.picture,
      protocol: ActiveStorage::Current.url_options[:protocol],
      host: ActiveStorage::Current.url_options[:host],
      port: ActiveStorage::Current.url_options[:port]
    )
  end
end

Guides Development Getting Started (`guides/development/getting_started.md`) Copy Section

Getting Started

Installation Copy Chapter

You can install graphql from RubyGems by adding to your application's Gemfile:

# Gemfile
gem "graphql"

Then, running bundle install:

$ bundle install

Getting Started Copy Chapter

On Rails, you can get started with a few GraphQL generators:

# Add graphql-ruby boilerplate and mount graphiql in development
$ rails g graphql:install
# You may need to run bundle install again, as by default graphiql-rails is added on installation.
$ bundle install
# Make your first object type
$ rails g graphql:object Post title:String rating:Int comments:[Comment]

Or, you can build a GraphQL server by hand:

• Define some types
• Connect them to a schema
• Execute queries with your schema

Declare types Copy Section

Types describe objects in your application and form the basis for GraphQL's type system.

# app/graphql/types/post_type.rb
module Types
  class PostType < Types::BaseObject
    description "A blog post"
    field :id, ID, null: false
    field :title, String, null: false
    # fields should be queried in camel-case (this will be `truncatedPreview`)
    field :truncated_preview, String, null: false
    # Fields can return lists of other objects:
    field :comments, [Types::CommentType],
      # And fields can have their own descriptions:
      description: "This post's comments, or null if this post has comments disabled."
  end
end

# app/graphql/types/comment_type.rb
module Types
  class CommentType < Types::BaseObject
    field :id, ID, null: false
    field :post, PostType, null: false
  end
end

Build a Schema Copy Section

Before building a schema, you have to define an entry point to your system, the "query root":

class QueryType < GraphQL::Schema::Object
  description "The query root of this schema"

  field :post, resolver: Resolvers::PostResolver
end

Define how this field is resolved by creating a resolver class:

# app/graphql/resolvers/post_resolver.rb
module Resolvers
  class PostResolver < BaseResolver
    type Types::PostType, null: false
    argument :id, ID

    def resolve(id:)
      ::Post.find(id)
    end
  end
end

Then, build a schema with QueryType as the query entry point:

class Schema < GraphQL::Schema
  query Types::QueryType
end

This schema is ready to serve GraphQL queries! Browse the guides to learn about other GraphQL Ruby features.

Execute queries Copy Section

You can execute queries from a query string:

query_string = "
{
  post(id: 1) {
    id
    title
    truncatedPreview
  }
}"
result_hash = Schema.execute(query_string)
# {
#   "data" => {
#     "post" => {
#        "id" => 1,
#        "title" => "GraphQL is nice"
#        "truncatedPreview" => "GraphQL is..."
#     }
#   }
# }

See Executing Queries for more information about running queries on your schema.

Use with Relay Copy Chapter

If you're building a backend for Relay, you'll need:

• A JSON dump of the schema, which you can get by sending GraphQL::Introspection::INTROSPECTION_QUERY
• Relay-specific helpers for GraphQL, see the Connection guide, Mutation guide, and Object Identification guide.

Use with Apollo Client Copy Chapter

Apollo Client is a full featured, simple to use GraphQL client with convenient integrations for popular view layers. You don't need to do anything special to connect Apollo Client to a graphql-ruby server.

Use with GraphQL.js Client Copy Chapter

GraphQL.js Client is a tiny client that is platform- and framework-agnostic. It works well with graphql-ruby servers, since GraphQL requests are simple query strings transported over HTTP.

Guides Development Related Projects (`guides/development/related_projects.md`) Copy Section

Related Projects

Want to add something? Please open a pull request on GitHub!

Code Copy Chapter

• graphql-ruby + Rails demo (src / heroku)
• graphql-ruby + Sinatra demo (src / heroku)
• graphql-batch, a batched query execution strategy
• graphql-cache, a resolver-level caching solution
• graphql-devise, a gql interface to handle authentication with Devise
• graphql-docs, a tool to automatically generate static HTML documentation from your GraphQL implementation
• graphql-metrics, a plugin to extract fine-grain metrics of GraphQL queries received by your server
• graphql-stitching, tools to combine multiple local and remote schemas into a single graph that queries as one
• graphql-groups, a DSL to define group- and aggregation queries with graphql-ruby
• Rails Helpers:
  • graphql-activerecord
  • graphql-rails-resolve
  • graphql-query-resolver, a graphql-ruby add-on to minimize N+1 queries.
  • graphql-rails_logger, a logger which allows you to inspect GraphQL queries in a more readable format.
  • apollo_upload_server-ruby, a middleware which allows you to upload files with GraphQL and multipart/form-data using apollo-upload-client library on front-end.
  • graphql-sources a collection of common GraphQL sources to simplify using ActiveRecord, ActiveStorage, Rails.cache, and more.
  • graphql-filters, a DSL to define fully typed filters for list fields.
• search_object_graphql, a DSL for defining search resolvers for GraphQL.
• action_policy-graphql, an integration for using action_policy as an authorization framework for GraphQL applications.
• graphql_rails, Rails way GraphQL build tool
• graphql-rails-generators, Generate graphql-ruby mutations, types and input types from your ActiveRecord models.
• graphql-ruby-fragment_cache, a tool for caching response fragments.
• graphql-ruby-persisted_queries, the implementation of Apollo persisted queries.
• rubocop-graphql, rubocop extension for enforcing best practices.
• apollo-federation-ruby, a Ruby implementation of the Apollo Federation subgraph spec.

Blog Posts Copy Chapter

• Building a blog in GraphQL and Relay on Rails Introduction, Part 1, Part 2
• https://medium.com/@khor/relay-facebook-on-rails-8b4af2057152
• https://blog.jacobwgillespie.com/from-rest-to-graphql-b4e95e94c26b#.4cjtklrwt
• https://jonsimpson.ca/parallel-graphql-resolvers-with-futures/
• Active Storage meets GraphQL: Direct uploads and Exposing attachment URLs
• Exposing permissions in GraphQL APIs with Action Policy
• Reporting non-nullable violations in graphql-ruby properly
• How to GraphQL with Ruby, Rails, Active Record, and no N+1

Screencasts Copy Chapter

• GraphQL Basics in Rails 5

Presentations Copy Chapter

• Rescuing Legacy Codebases with GraphQL by @nettofarah

Tutorials Copy Chapter

• How To GraphQL by @rstankov

• GraphQL Ruby CRUD Tutorial by @kohheepeace

• Rails/GraphQL + React/Apollo Tutorial (Part 1, Part 2, Part 3) by @evilmartians

Guides Errors Error Handling (`guides/errors/error_handling.md`) Copy Section

Error Handling

You can configure your schema to rescue application errors during field resolution. Errors during batch loading will also be rescued.

Thanks to @exAspArk for the graphql-errors gem which inspired this behavior and @thiago-sydow who suggested an implementation like this.

Add error handlers Copy Chapter

Handlers are added with rescue_from configurations in the schema:

class MySchema < GraphQL::Schema
  # ...

  rescue_from(ActiveRecord::RecordNotFound) do |err, obj, args, ctx, field|
    # Raise a graphql-friendly error with a custom message
    raise GraphQL::ExecutionError, "#{field.type.unwrap.graphql_name} not found"
  end

  rescue_from(SearchIndex::UnavailableError) do |err, obj, args, ctx, field|
    # Log the error
    Bugsnag.notify(err)
    # replace it with nil
    nil
  end
end

The handler is called with several arguments:

• err is the error that was raised during field execution, then rescued
• obj is the object which was having a field resolved against it
• args is the Hash of arguments passed to the resolver
• ctx is the query context
• field is the GraphQL::Schema::Field instance for the field where the error was rescued

Inside the handler, you can:

• Raise a GraphQL-friendly GraphQL::ExecutionError to return to the user
• Re-raise the given err to crash the query and halt execution. (The error will propagate to your application, eg, the controller.)
• Report some metrics from the error, if applicable
• Return a new value to be used for the error case (if not raising another error)

Guides Errors Execution Errors (`guides/errors/execution_errors.md`) Copy Section

The GraphQL specification allows for a top-level "errors" key in the response which may contain information about what went wrong during execution. For example:

{
  "errors" => [ ... ]
}

The response may include both "data" and "errors" in the case of a partial success:

{
  "data" => { ... } # parts of the query that ran successfully
  "errors" => [ ... ] # errors that prevented some parts of the query from running
}

When to Use Top-Level Errors Copy Chapter

In general, top-level errors should only be used for exceptional circumstances when a developer should be made aware that the system had some kind of problem.

For example, the GraphQL specification says that when a non-null field returns nil, an error should be added to the "errors" key. This kind of error is not recoverable by the client. Instead, something on the server should be fixed to handle this case.

When you want to notify a client some kind of recoverable issue, consider making error messages part of the schema, for example, as in mutation errors.

Adding Errors to the Array Copy Chapter

In GraphQL-Ruby, you can add entries to this array by raising GraphQL::ExecutionError (or a subclass of it), for example:

raise GraphQL::ExecutionError, "Can't continue with this query"

When this error is raised, its message will be added to the "errors" key and GraphQL-Ruby will automatically add the line, column and path to it. So, the above error might be:

{
  "errors" => [
    {
      "message" => "Can't continue with this query",
      "locations" => [
        {
          "line" => 2,
          "column" => 10,
        }
      ],
      "path" => ["user", "login"],
    }
  ]
}

Customizing Error JSON Copy Chapter

The default error JSON includes "message", "locations" and "path". The forthcoming version of the GraphQL spec recommends putting custom data in the "extensions" key of the error JSON.

You can customize this in two ways:

• Pass extensions: when raising an error, for example:

  ruby Copy

  raise GraphQL::ExecutionError.new("Something went wrong", extensions: { "code" => "BROKEN" })

  In this case, "extensions" => { "code" => "BROKEN" } will be added to the error JSON.

• Override #to_h in a subclass of GraphQL::ExecutionError, for example:

  ruby Copy

  class ServiceUnavailableError < GraphQL::ExecutionError
    def to_h
      super.merge({ "extensions" => {"code" => "SERVICE_UNAVAILABLE"} })
    end
  end

  Now, "extensions" => { "code" => "SERVICE_UNAVAILABLE" } will be added to the error JSON.

Guides Errors Type Errors (`guides/errors/type_errors.md`) Copy Section

Type Errors

The GraphQL specification requires certain assumptions to hold true when executing a query. However, it's possible that some code would violate that assumption, resulting in a type error.

Here are two type errors that you can customize in GraphQL-Ruby:

• A field with null: false returned nil
• A field returned a value as a union or interface, but that value couldn't be resolved to a member of that union or interface.

You can specify behavior in these cases by defining a Schema.type_error hook:

class MySchema < GraphQL::Schema
  def self.type_error(err, query_ctx)
    # Handle a failed runtime type coercion
  end
end

It is called with an instance of GraphQL::UnresolvedTypeError or GraphQL::InvalidNullError and the query context (a GraphQL::Query::Context).

If you don't specify a hook, you get the default behavior:

• Unexpected nils add an error the response's "errors" key
• Unresolved Union / Interface types raise GraphQL::UnresolvedTypeError

An object that fails type resolution is treated as nil.

Guides Execution Migration (`guides/execution/migration.md`) Copy Section

Migrating to Execution::Next

This guide includes tips for migrating your schema configuration and production traffic to the new engine.

Migration Philosophy Copy Chapter

Execution::Next is designed to run alongside the previous engine so that the same schema can run queries both ways. This supports an incremental migration and live toggling in production.

First, update your schema to include the necessary field configurations. If you implement new class methods in your Object type classes, you can also migrate instance methods to call "up" to those class methods, preserving a single source of truth:

field :unpublished_posts, [Types::Post], resolve_each: true

# Support batching:
def self.unpublished_posts(object, context)
  object.posts.where(published: false).order("created_at DESC")
end

# Support legacy in a DRY way by calling the class method:
def unpublished_posts
  self.class.unpublished_posts(object, context)
end

Test your new configurations in CI by running a new build which calls execution_next instead of execution, for example:

# test_helpers.rb
def run_graphql(...)
  if ENV["GRAPHQL_EXECUTION_NEXT"]
    MyAppSchema.execute_next(...)
  else
    MyAppSchema.execute(...)
  end
end

Adopting a feature flag system (described below) can also make this easier.

When all tests pass on .execute_next, you're ready to try it out in production.

Migration and Clean-Up Script Copy Chapter

graphql_migrate_execution is a command-line development tool that can automate many common GraphQL-Ruby field resolver patterns.

Check out its docs and try out: https://rmosolgo.github.io/graphql_migrate_execution/

Production Considerations Copy Chapter

There are two categories of problems when migrating:

• Some schema misconfigurations may only be detected at runtime.
• The engine may have bugs. (It's brand-new code trying to emulate 10 years of incremental development!)

When migrating, these possibilities should be considered from three different angles. Using the new engine may...

• ...raise errors in new ways.
• ...return a different result than the old engine.
• ...perform worse than the old engine, especially because of different database access patterns.

To mitigate these possibilities, use dynamic release tools in production like feature flags and experiments.

Feature Flags Copy Section

You should use a feature flagging system so that you can shift traffic between old and new runtime engines without redeploying. A good feature-flagging system supports percentage-based flags, so that you can send 1% of traffic to new code while the other 99% uses existing code. After it runs without issues, you can increase the percentage. Or, if you discover issues in production (errors or performance), you can turn it back to 0% while you troubleshoot the problem.

For example:

# app/controllers/graphql_controller.rb
exec_method = use_graphql_next? ? :execute_next : :execute
result = MyAppSchema.public_send(exec_method, query_string, context: { ... }, variables: { ... })
render json: result

Flipper is a great gem for feature flags. You could also roll your own or pick a third-party service.

Before using .execute_next to produce results for production traffic, you might want to run an experiment as described below.

Experiments Copy Section

While the two runtime engines should return identical responses, it's possible that .execute_next will return a different result than .execute due to gem bugs or schema misconfigurations. You can check for this using an "experiment" system in your application which runs both execution engines and compares the result (for queries only!).

You'll want to use feature flagging to run the experiment on a subset of traffic, since it comes with performance overhead.

Here's some example code for a setup like this:

# app/controllers/graphql_controller.rb
result = MySchema.execute(...)

# Use a dynamic flag, eg Flipper. This should always be true in development and test.
if use_graphql_next_experiment?
  if !query_string.include?("mutation") && !query_string.include?("subscription") # easy way of checking for queries, could possibly have false negatives
    batched_result = MySchema.execute_next(...)
    if batched_result.to_h != result.to_h
      # Log this mismatch somehow here, avoiding potential PII/passwords:
      BugTracker.report <<~TXT
        A GraphQL query returned a non-identical response. Sanitized query string:

        #{result.query.sanitized_query_string}

        User: #{current_user.id}
        # Other context info here...
      TXT
    end
  end
end

See Scientist for a full-blown production experimentation system.

Combining feature flags and experiments Copy Chapter

A fully-managed rollout would include two flags:

• use_graphql_next_experiment?: when true, build an .execute_next response and compare it to the .execute response. But always return the .execute response.
• use_graphql_next?: when true, use .execute_next and don't call .execute at all

This gives you full control over how production traffic is executed without needing to redeploy. You can always turn them down to 0% to get the current behavior.

Here's some example code:

if use_graphql_next? # again, use a dynamic feature flag
  result = MySchema.execute_next(...)
else
  result = MySchema.execute(...)
  if use_graphql_next_experiment?
    # Continue running the comparison experiment
  end
end

render json: result.to_h

Compatibility Notes Copy Chapter

Execution::Next's new structure means that some GraphQL-Ruby features behave differently (or aren't supported at all, at least not yet). They are discussed one-by-one below.

Implicit Field Resolution Copy Section

The default, implicit field resolution behavior has changed. Previously, when a field didn't have a specified method or hash key, GraphQL-Ruby would try a combination of object.public_send(...) and object[...] to resolve it. In Execution::Next, GraphQL-Ruby tries object.public_send(field_sym) unless another configuration is provided. This removes a lot of overhead from field execution.

Consider a field like this:

field :title, String

Previously, GraphQL-Ruby would check type_object.respond_to?(:title), object.respond_to?(:title), object.is_a?(Hash). object.key?(:title) and object.key?("title").

Now, GraphQL-Ruby simply calls object.title and allows the NoMethodError to bubble up if one is raised.

Interface Resolver Methods Copy Section

Resolver methods are now class methods instead of instance methods. In order to make this work in interface modules, they must be defined in a resolver_methods do ... end block, for example:

module Node
  include BaseInterface

  field :id, ID, resolve_each: true

  resolver_methods do
    # This will define `def self.id` on Object types that implement this interface
    def id(object, context)
      GlobalId.new(object).to_s
    end
  end

  # Backwards compat instance method:
  def id
    self.class.id(object, context)
  end
end

Methods defined in resolver_methods { ... } will be copied into Object type classes as class methods, so they'll be available for resolve_{each|static|batch} fields.

Query Analyzers, including complexity 🟡 Copy Section

Support is identical; this runs before execution using the exact same code.

TODO: accessing loaded arguments inside analyzers may turn out to be slightly different; it still calls legacy code.

Authorization, Scoping Copy Section

def (self.)authorized? and def self.scope_items will be called as needed during execution.

One incompatibility:

• Argument #authorized? will be called if the argument wasn't present in the query but a default value is used. Execution::Next doesn't create the metadata necessary to skip authorization in that case. A work-around might be to check if the value is equal to the default value in def authorized? and permit it if it is. If this is a blocker for you, please open an issue on GitHub and we can check it out.

Visibility, including Changesets Copy Section

Visibility works exactly as before; both runtime modules call the same methods to get type information from the schema.

Dataloader Copy Section

Dataloader runs with new execution, but when migrating from instance methods to batch-level class methods, you may need to use Schema::Member::HasDataloader#dataload_all instead of .dataload.

Tracing Copy Section

Fully supported, but some legacy hooks are not called. Implement the new hooks instead (existing runtime already calls these new hooks). Not called are:

• execute_field, execute_field_lazy: use begin_execute_field, end_execute_field instead. (These may be called multiple times when Dataloader pauses or a GraphQL-Batch promise is returned)
• execute_query, execute_query_lazy: use execute_multiplex for a top-level hook instead. (Single queries are always executed in a multiplex of size = 1.)
• resolve_type, authorized: use {begin,end}_resolve_type and {begin,end}_authorized instead. (May be called multiple times for Dataloader etc.)

Additionally, object parameters to those methods will receive an Array of objects instead.

Lazy resolution (GraphQL-Batch) Copy Section

Lazy resolution runs in the new execution (GraphQL-Batch is supported). When migrating to class methods, you may need to update your library method calls to work on a set of inputs rather than a single input.

`current_path` ❌ Copy Section

This is not supported because the new runtime doesn't actually produce current_path.

It is theoretically possible to support this but it will be a ton of work. If you use this for core runtime functions, please share your use case in a GitHub issue and we can investigate future options.

Scoped context ❌ Copy Section

This is currently implemented with current_path. Another implementation is probably possible but not implemented yet. Please open an issue to discuss.

`@defer` 🟡 Copy Section

@defer is supported with an implementation difference that probably doesn't affect your application: previously, @defer worked by pausing and resuming the same GraphQL::Query instance. However, with Execution::Next, @defer takes a different approach. Instead, when a GraphQL::Query encounters @defer, it notes the location in the document and stops executing that branch. Later, when you request the deferred result, that branch of the query is resumed using a new instance of GraphQL::Query::Partial.

This might matter if you're modifying context at runtime because those new instances also have fresh Query::Context instances. The original query context will get copied into the @defer branches using Query::Context.new(**original_query.context.to_h), so any custom values will be available. But if you assign new keys after the context is copied, those keys won't appear when running later @defered branches.

To handle this, you can refactor how you accumulate data during execution. Instead of ||='ing into context[...] during execution, assign a new accumulator object before starting the query, then call methods on that object to make any necessary state changes. That new object will be copied into @defer partials, and since the object is shared between the different branches, any necessary state changes will still be "seen" everywhere.

If this gives you trouble, please feel free to email me or open an issue on GitHub to discuss a migration strategy.

GraphQL-Batch support

When using Execution::Next, no custom code is required to support graphql-batch -- support is built-in.

`@stream` Copy Section

@stream is supported.

See the not above about how @defer no longer resumes the original, top-level query. The same thing applies to @stream.

GraphQL::Pro::Stream now lazily streams Enumerators. If you were using the (undocumented) GraphQL::Pro::FutureStream, you can switch to GraphQL::Pro::Stream after migrating to Execution::Next. (Once all your traffic uses the new execution module, you'll get the same runtime behavior from GraphQL::Pro::Stream.)

ObjectCache Copy Section

Supported completely.

Custom Directives ❌ Copy Section

There is some implementation in the code right now but it's not stable. Please open an issue to discuss.

Query-level directives are not implemented yet, but will be. Please open an issue if you have a use case for this.

`as:` Copy Section

as: is applied: arguments are passed into Ruby methods by their as: names instead of their GraphQL names.

`loads:` 🟡 Copy Section

loads: is handled as previously, except that custom def load_... methods are not called.

`prepare:` 🟡 Copy Section

Procs are called as before.

Methods that depend on a runtime object (such as a type instance or Mutation class) are not called, because arguments are prepared before objects are ready.

`validates:` 🟡 Copy Section

Built-in validators are supported. Custom validators will always receive nil as the object. (object is no longer available; this API will probably change before this is fully released.)

Field Extensions 🟡 Copy Section

Field extension methods are called with new arguments:

• objects: instead of object:, with an Array
• values: instead of value:, with an Array

You can support both types of calls in your methods by changing the signature to object: nil, objects: nil (and value: nil, values: nil), then checking which argument was passed.

Resolver classes (including Mutations and Subscriptions) 🟡 Copy Section

Resolver classes are called, but with slightly different semantics:

• #ready? is still called, but after arguments are loaded. It's now a useless method and will probably be deprecated.
• def load_... methods are not called; instead, arguments are passed to the top-level Schema.object_from_id hook.

Field `extras:`, including `lookahead` Copy Section

:ast_node and :lookahead are already implemented. Others are possible -- please raise an issue if you need one. extras: [:current_path] is not possible.

`raw_value` 🟡 Copy Section

Supported, but the raw_value call must be made on context, for example:

field :values, SomeObjectType, resolve_static: true

def self.values(context)
  context.raw_value(...)
end

Errors and `rescue_from` 🟡 Copy Section

Raising GraphQL::ExecutionError and adding rescue_from handlers are supported

Returning an array of GraphQL::ExecutionError instances is not supported anymore.

extras: [:execution_errors] and context.add_error are not supported anymore.

Connection fields Copy Section

Connection arguments are automatically handled and connection wrapper objects are automatically applied to arrays and relations.

Custom Introspection Copy Section

This works but if you want custom authorization or any lazy values, see notes about that compatibility.

If you're reimplementing default values, you'll need to add the corresponding resolve_static: true or resolve_each: true configurations. See the built-in type definitions under GraphQL::Introspection to get these configurations.

Multiplex Copy Section

To use the new engine to run a multiplex, use MyAppSchema.multiplex_next(...) with the same arguments.

GraphQL::Current 🟡 Copy Section

current_field doesn't work; dataloader_source works. current_operation_name doesn't work.

This will be fixed soon but may require opt-in to avoid needless overhead.

`fallback_value:` ❌ Copy Section

fallback_value: is not supported in Execution::Next. It's not implemented because of the overhead it adds to resultion. You'll have to implement it by hand in resolvers.

graphql_migrate_execution creates a resolver that always returns the fallback_value. This might be right in some cases, but you'll probably have to implement your own method, like:

field :name, String, fallback_value: "Anonymous", resolve_each: :resolve_name

def resolve_name(object, context)
  if object.respond_to?(:name)
    object.name
  elsif (is_h = object.is_a?(Hash)) && object.key?(:name)
    object[:name]
  elsif is_h && object.key?("name")
    object["name"]
  else
    "Anonymous"
  end
end

GraphQL::Backtrace Copy Chapter

Doesn't support Execution::Next, but it's probably not necessary. Execution::Next includes the field name in error messages and doesn't generate crazy-long stack traces because of its design.

Guides Execution Next (`guides/execution/next.md`) Copy Section

New Execution Module

GraphQL-Ruby has a new execution engine, GraphQL::Execution::Next. It's much faster and less memory-consuming than the existing execution engine, but requires some care in migrating.

This feature is in heavy development, so if you give it a try and run into any problems, please open an issue on GitHub!

Background Copy Chapter

Breadth-first GraphQL execution (or, "execution batching") is an algorithmic paradigm developed by Shopify to address problems of scale when resolving large lists and nested sets. Rather than paying field-level overhead costs (resolver calls, instrumentation, lazy promises, etc) for every field of every resolved object, the pattern instead incurs these costs only once per field selection and runs the corresponding breadth of objects with no additional overhead.

The original proof-of-concept of Shopify's core algorithm and white paper notes can be found in graphql-breadth-exec. That prototype matured into Shopify's proprietary GraphQL Cardinal execution engine that now runs much of their core traffic.

GraphQL-Ruby brings these breadth-first design principles to the open-source community with several novel techniques for implementing GraphQL:

• Fields are resolved breadth-first using implicitly batched resolvers. These run longer and hotter on application logic with no execution overhead.
• Batched resolvers may bind entire load sets to a single lazy promise to dramatically reduce promise bloat.
• Error handling is optimized into a second pass that only runs when errors actually occur.
• Stack profiling becomes much more organized with a linear flow and aggregate field spans, rather than fields getting split up across subtree repetitions.
• The engine is driven by enqueuing rather than recursion, which shrinks stack traces and reduces memory usage.

Breadth-first patterns can produce dramatic results in responses with a high degree of repetition: it's not uncommon to see breadth batching run 15x faster and use 75% less memory than classic GraphQL Ruby execution. However – gains are relative. A flat tree with no lists will see little difference. A list of 2 resolving one field each will see a small gain, while a list of 100 resolving ten fields each will likely see dramatic results.

The downside is that many of GraphQL-Ruby's "bonus features" -- those that go beyond the behavior described in the GraphQL Specification -- add non-trivial overhead when used. So, the task ahead is to "lift the ceiling" of performance in GraphQL-Ruby while retaining as much compatibility as possible and supporting a gradual transition to this new runtime engine.

Enabling Execution::Next Copy Chapter

The new execution engine is enabled with two steps:

• Add the plugin to your schema with use GraphQL::Execution::Next
• Call MySchema.execute_next(...) instead of MySchema.execute(...). It takes the same arguments.

See compatibility notes for updating your schema to run queries with the new engine.

You can also add ..., as_default: true to use execute_next by default. In that case, call execute_legacy if you need the old runtime.

Field configurations Copy Chapter

The new runtime engine supports several field resolution configurations out of the box.

Method calls (default, `method:`) Copy Section

These fields call object.#{field_name}. This is the default, and the method name can be overridden with method: ...:

field :title, String # calls object.title
field :title, String, method: :get_title_somehow # calls object.get_title_somehow

Hash keys (`hash_key:`) Copy Section

These fields call object[hash_key], configured with hash_key: ....

field :title, String, hash_key: :title # calls object[:title]
field :title, String, hash_key: "title" # calls object["title"]

Note: new execution doesn't "fall back" to hash key lookups, and it doesn't try strings when Symbols are given. The existing runtime engine does that, but it has been excluded for performance reasons. To get the old resolution behavior, you can code it like:

field :title, String, resolve_each: true

def self.title(object, context)
  # For example, try a symbol key first, then a string:
  object[:title] || object["title"]
end

Per-object (`resolve_each:`) Copy Section

These fields use a class method to produce a result for each object, configured with resolve_each:.

field :title, String, resolve_each: true do # calls `self.title(...)` below
  argument :language, Types::Language, required: false, default_value: "EN"
end

def self.title(object, context, language:)
  # Assuming this makes no database lookups or other external service calls:
  object.localization.get(:title, language:)
end

The default method is the same as the field name symbol. You can also provide a custom method:

# Avoid a conflict with Ruby's built-in `Class#name`:
field :name, String, resolve_each: :get_name

def self.get_name(object, context)
  # ...
end

Under the hood, GraphQL-Ruby calls objects.map { ... }, calling this class method.

‼️ Don't use this if your logic calls external services or databases (including with Dataloader). If you do, your I/O will be sequential instead of batched. Use resolve_batch: or resolve_static: instead, see below.

Global (`resolve_static:`) Copy Section

Fields that use a class method to produce a single result shared by all objects, configured with resolve_static:. The method does not receive any object, only context:

field :posts_count, Integer, resolve_static: :count_all_posts do
  argument :include_unpublished, Boolean, required: false, default_value: false
end

def self.count_all_posts(context, include_unpublished:)
  posts = Post.all
  if !include_unpublished
    posts = posts.published
  end
  posts.count
end

Under the hood, GraphQL-Ruby calls Array.new(objects.size, static_result).

Batch resolvers (`resolve_batch:`) Copy Section

This is a high-performance option for when you need to do I/O to generate results. By working with a batch of objects, you can greatly reduce the framework overhead in preparing a result.

These fields use a class method to map parent objects to field results, configured with resolve_batch::

field :title, String, resolve_batch: true do # calls self.title below
  argument :language, Types::Language, required: false, default_value: "EN"
end

def self.title(objects, context, language:)
  # This is equivalent to plain `field :title, ...`, but for example:
  objects.map { |obj| obj.title(language:) }
end

This is especially useful when batching Dataloader calls:

class Types::Comment < BaseObject
  field :author_rating, Integer, resolve_batch: true

  def self.author_rating(objects, context)
    authors = context.dataload_all_records(objects, :author)
    context.dataload_all(Sources::AuthorRating, authors)
  end
end

By default, it calls a class method matching the field name. You can customize this configuration, too:

field :author_rating, Integer, resolve_batch: :calculate_rating # calls `self.calculate_rating(objects, context)`

def self.calculate_rating(objects, context)
  # ...
end

Dataloader Copy Section

Execution::Next supports field configuration shorthands for common dataloader usage. Under the hood, these make sure data fetching is batched and cached.

method: can be added to any hash-style dataload: config to call a public method on the loaded value.

Sources

Use a custom dataloader source from your application:

class Types::CommentType
  # Equivalent to `dataload(Sources::CommentRating, object)`
  field :rating, Integer, dataload: Sources::CommentRating

  # `using:`: A method to call to get a value to pass to dataloader
  # `by: [...]`: An array of arguments to pass on to dataloader
  #
  # Equivalent to `dataload(Sources::ReadingDuration, :comment, object.body)
  field :reading_duration, Integer, dataload: { with: Sources::ReadingDuration, using: :body, by: [:comment] }

  # `method:`: A method to call on the loaded value
  #
  # Equivalent to `dataload(Sources::CommentRating, object).to_s`
  field :rating_string, String, dataload: { with: Sources::CommentRating, method: :to_s }

Rails Associations

Load ActiveRecord associations using GraphQL::Dataloader::ActiveRecordAssociationSource:

class Types::CommentType < Types::BaseObject
  # Equivalent to `dataload_association(:post)`
  field :post, Types::Post, dataload: { association: true }
  # Equivalent to `dataload_association(:user)
  field :author, Types::Post, dataload: { association: :user }
  # Equivalent to `dataload_association(:author)&.name`
  field :author_name, String, null: true, dataload: { association: :author, method: :name }
end

Rails Records

Load ActiveRecord associations using GraphQL::Dataloader::ActiveRecordSource.

class Types::SearchResult < Types::BaseObject
  # Equivalent to `dataload_record(Post, object.post_id)`
  field :post, Types::Post, dataload: { model: Post, using: :post_id }
  # Equivalent to `dataload_record(User, object.created_by_handle, find_by: :handle)`
  field :author, Types::User, dataload: { model: User, using: :created_by_handle, find_by: :handle }
  # Equivalent to `dataload_record(Post, object.post_id)&.title`
  field :post_title, String, null: true, dataload: { model: Post, using: :post_id, method: :title }
end

Legacy instance methods Copy Section

resolve_legacy_instance_method:

There is partial support for instance methods on Object type classes, for now. It will be deprecated and removed soon.

‼️ Don't use legacy instance methods with Dataloader. It will be sequential, not batched. ‼️

field :title, String, resolve_legacy_instance_method: true do
  argument :language, Types::Language, required: false, default_value: "EN"
end

def title(language:)
  # Assuming this makes no database lookups or other external service calls:
  object.localization.get(:title, language:)
end

Under the hood, GraphQL-Ruby calls objects.map { ... }, calling this instance method. It adds significant overhead because GraphQL-Ruby initializes the object type class.

`true` shorthand Copy Section

There is also a true shorthand: when one of the resolve_...: configurations is passed as true (ie, resolve_batch: true, resolve_each: true, resolve_static: true, or resolve_legacy_instance_method: true), then the Symbol field name is used as the class method. For example:

field :posts_count, Integer, resolve_static: true

def self.posts_count(context)
  Post.all.count
end

Migration Copy Chapter

Read about migrating in the Migration Doc.

Guides Fields Arguments (`guides/fields/arguments.md`) Copy Section

Arguments

Arguments are part of the GraphQL::Schema::Argument API. The complete
reference, including nullability, defaults, deprecation, aliasing,
preprocessing, camelization, and supported input types, is maintained with
the implementation:

GraphQL::Schema::Argument

Use that API reference for the exact argument(...) parameters and runtime
behavior. This guide remains the entry point for field arguments and connects
the topic to the fields and
validation guides.

Guides Fields Introduction (`guides/fields/introduction.md`) Copy Section

Field definitions

Field definitions are part of the GraphQL::Schema::Field API. The complete
reference, including names, return types, descriptions, resolution behavior,
arguments, extras, and default options, is maintained with the implementation:

GraphQL::Schema::Field

Use that API reference when you need the exact field(...) parameters and
runtime behavior. This guide remains the entry point for the fields section
and links to the related objects,
interfaces, and
arguments guides.

Field Names Copy Chapter

See the Field API reference.

Field Return Type Copy Chapter

See the Field API reference.

Field Documentation Copy Chapter

See the Field API reference.

Field Resolution Copy Chapter

See the Field API reference.

Field Arguments Copy Chapter

See the Field API reference.

Extra Field Metadata Copy Chapter

See the Field API reference.

Field Parameter Default Values Copy Chapter

See the Field API reference.

Guides Fields Limits (`guides/fields/limits.md`) Copy Section

Limits

List Fields Copy Chapter

Always limit the number of items which can be returned from a list field. For example, use a limit: argument and make sure it's not too big. The prepare: function provides a convenient place to cap the number of items:

field :items, [Types::ItemType] do
  # Cap the number of items at 30
  argument :limit, Integer, default_value: 20, prepare: ->(limit, ctx) {[limit, 30].min}
end

def items(limit:)
  object.items.limit(limit)
end

This way, you won't hit your database for 1000 items!

Connections Copy Chapter

Connections accept a max_page_size option which limits the number of nodes.

Guides Fields Resolvers (`guides/fields/resolvers.md`) Copy Section

Resolvers

A GraphQL::Schema::Resolver is a container for field signature and resolution logic. It can be attached to a field with the resolver: keyword:

# Use the resolver class to execute this field
field :pending_orders, resolver: PendingOrders

Under the hood, GraphQL::Schema::Mutation is a specialized subclass of Resolver.

First, ask yourself ... Copy Chapter

Do you really need a Resolver? Putting logic in a Resolver has some downsides:

• Since it's coupled to GraphQL, it's harder to test than a plain ol' Ruby object in your app
• Since the base class comes from GraphQL-Ruby, it's subject to upstream changes which may require updates in your code

Here are a few alternatives to consider:

• Put display logic (sorting, filtering, etc.) into a plain ol' Ruby class in your app, and test that class
• Hook up that object with a method, for example:

field :recommended_items, [Types::Item], null: false
def recommended_items
  ItemRecommendation.new(user: context[:viewer]).items
end

• If you have lots of arguments to share, use a class method to generate fields, for example:

# Generate a field which returns a filtered, sorted list of items
def self.items_field(name, override_options, &block)
  # Prepare options
  default_field_options = { type: [Types::Item], null: false }
  field_options = default_field_options.merge(override_options)
  # Create the field
  field(name, **field_options) do
    argument :order_by, Types::ItemOrder, required: false
    argument :category, Types::ItemCategory, required: false
    # Allow an override block to add more arguments
    instance_eval(&block) if block_given?
  end
end

# Then use the generator to create a field:
items_field(:recommended_items) do |field|
  field.argument :similar_to_product_id, ID, required: false
end
# Implement the field
def recommended_items
  # ...
end

As a matter of code organization, that class method could be put in a module and shared between different classes that need it.

• If you need the same logic shared between several objects, consider using a Ruby module and its self.included hook, for example:

module HasRecommendedItems
  def self.included(child_class)
    # attach the field here
    child_class.field(:recommended_items, [Types::Item], null: false)
  end

  # then implement the field
  def recommended_items
    # ...
  end
end

# Add the field to some objects:
class Types::User < BaseObject
  include HasRecommendedItems # adds the field
end

• If the module approach looks good to you, also consider Interfaces. They also share behavior between objects (since they're just modules that get included, after all), and they expose that commonality to clients via introspection.

When do you really need a resolver? Copy Chapter

So, if there are other, better options, why does Resolver exist? Here are a few specific advantages:

• Isolation. A Resolver is instantiated for each call to the field, so its instance variables are private to that object. If you need to use instance variables for some reason, this helps. You have a guarantee that those values won't hang around when the work is done.
• Complex Schema Generation. RelayClassicMutation (which is a Resolver subclass) generates input types and return types for each mutation. Using a Resolver class makes it easier to implement, share and extend this code generation logic.

Using `resolver` Copy Chapter

Use the base resolver class:

module Resolvers
  class RecommendedItems < BaseResolver
    type [Types::Item], null: false
    description "Items this user might like"

    argument :order_by, Types::ItemOrder, required: false
    argument :category, Types::ItemCategory, required: false

    def resolve(order_by: nil, category: nil)
      # call your application logic here:
      recommendations = ItemRecommendation.new(
        viewer: context[:viewer],
        recommended_for: object,
        order_by: order_by,
        category: category,
      )
      # return the list of items
      recommendations.items
    end
  end
end

And attach it to your field:

class Types::User < Types::BaseObject
  field :recommended_items, resolver: Resolvers::RecommendedItems
end

Since the Resolver lifecycle is managed by the GraphQL runtime, the best way to test it is to execute GraphQL queries and check the results.

Nesting resolvers of the same type Copy Section

You may run into cyclical loading issues when using a resolver within the definition of the type the resolver returns e.g.

# app/graphql/types/query_type.rb

module Types
  class QueryType < Types::BaseObject
    field :tasks, resolver: Resolvers::TasksResolver
  end
end

# app/graphql/types/task_type.rb

module Types
  class TaskType < Types::BaseObject
    field :title, String, null: false
    field :tasks, resolver: Resolvers::TasksResolver
  end
end

# app/graphql/resolvers/tasks_resolver.rb

module Resolvers
  class TasksResolver < BaseResolver
    type [Types::TaskType], null: false

    def resolve
      []
    end
  end
end

The above can produce the following error: Failed to build return type for Task.tasks from nil: Unexpected type input: (NilClass).

A simple solution is to express the type as a string in the resolver:

module Resolvers
  class TasksResolver < BaseResolver
    type "[Types::TaskType]", null: false

    def resolve
      []
    end
  end
end

In doing so, you can defer the loading of the type class until the nested resolver has already been loaded.

Extensions

In cases when you want your resolvers to add some extensions to the field they resolve, you can use extension method, which accepts extension class and options. Multiple extensions can be configured for a single resolver.

class GreetingExtension < GraphQL::Schema::FieldExtension
  def resolve(object:, arguments:, **rest)
    name = yield(object, arguments)
    "#{options[:greeting]}, #{name}!"
  end
end

class ResolverWithExtension < BaseResolver
  type String, null: false

  extension GreetingExtension, greeting: "Hi"

  def resolve
    "Robert"
  end
end

Guides Fields Validation (`guides/fields/validation.md`) Copy Section

Validation

Arguments can be validated at runtime using built-in or custom validators.

Validations are configured in argument(...) calls on fields or input objects:

argument :home_phone, String,
  description: "A US phone number",
  validates: { format: { with: /\d{3}-\d{3}-\d{4}/ } }

or, validates required: { ... } inside a field ... do ... end block:

field :comments, [Comment],
  description: "Find comments by author ID or author name" do
  argument :author_id, ID, required: false
  argument :author_name, String, required: false
  # Either `authorId` or `authorName` must be provided by the client, but not both:
  validates required: { one_of: [:author_id, :author_name] }
end

Validations can be provided with a keyword (validates: { ... }) or with a method inside the configuration block (validates ...).

Built-In Validations Copy Chapter

See each validator's API docs for details:

• length: { maximum: ..., minimum: ..., is: ..., within: ... } Schema::Validator::LengthValidator
• format: { with: /.../, without: /.../ } Schema::Validator::FormatValidator
• numericality: { greater_than:, greater_than_or_equal_to:, less_than:, less_than_or_equal_to:, other_than:, odd:, even: } Schema::Validator::NumericalityValidator
• inclusion: { in: [...] } Schema::Validator::InclusionValidator
• exclusion: { in: [...] } Schema::Validator::ExclusionValidator
• required: { one_of: [...] } Schema::Validator::RequiredValidator
• allow_blank: true|false Schema::Validator::AllowBlankValidator
• allow_null: true|false Schema::Validator::AllowNullValidator
• all: { ... } Schema::Validator::AllValidator

Some of the validators accept customizable messages for certain validation failures; see the API docs for examples.

allow_blank: and allow_null: may affect other validations, for example:

validates: { format: { with: /\A\d{4}\Z/ }, allow_blank: true }

Will permit any String containing four digits, or the empty string ("") if Rails is loaded. (GraphQL-Ruby checks for .blank?, which is usually defined by Rails.)

Alternatively, they can be used alone, for example:

argument :id, ID, required: false, validates: { allow_null: true }

Will permit any query that passes id: null.

Validation options may also be passed as procs that accept no parameters, for example:

validates :title, String, validates: { format: { with: -> { Flipper.enabled?(:new_title_format) ? NEW_TITLE_FORMAT : /.*/ }}

Custom Validators Copy Chapter

You can write custom validators, too. A validator is a class that extends GraphQL::Schema::Validator. It should implement:

• def initialize(..., **default_options) to accept any validator-specific options and pass along the defaults to super(**default_options)
• def validate(_empty, context, value) which is called at runtime to validate value. It may return a String error message or an Array of Strings. GraphQL-Ruby will add those messages to the top-level "errors" array along with runtime context information.

Then, custom validators can be attached either:

• directly, passed to validates, like validates: { MyCustomValidator => { some: :options }
• by keyword, if the keyword is registered with GraphQL::Schema::Validator.install(:custom, MyCustomValidator). (That would support validates: { custom: { some: :options }}).)

Validators are initialized when the schema is constructed (at application boot), and validate(...) is called while executing the query. There's one Validator instance for each configuration on each field, argument, or input object. (Validator instances aren't shared.)

Guides Javascript Client Apollo Subscriptions (`guides/javascript_client/apollo_subscriptions.md`) Copy Section

Apollo Subscriptions

GraphQL-Ruby's JavaScript client includes several kinds of support for Apollo Client:

• Apollo Link (2.x, 3.x):
  • Overview
  • Pusher
  • Ably
  • ActionCable
• Apollo 1.x:
  • Overview
  • Pusher
  • ActionCable

Apollo Link Copy Chapter

Apollo Links are used by Apollo client 2.x and 3.x.

Apollo Link -- Pusher Copy Chapter

graphql-ruby-client includes support for subscriptions with Pusher and ApolloLink.

To use it, add PusherLink before your HttpLink.

For example:

// Load Apollo stuff
import { ApolloClient, HttpLink, ApolloLink, InMemoryCache } from "@apollo/client";
// Load PusherLink from graphql-ruby-client
import PusherLink from 'graphql-ruby-client/subscriptions/PusherLink';

// Load Pusher and create a client
import Pusher from "pusher-js"
var pusherClient = new Pusher("your-app-key", { cluster: "us2" })

// Make the HTTP link which actually sends the queries
const httpLink = new HttpLink({
  uri: '/graphql',
  credentials: 'include'
});

// Make the Pusher link which will pick up on subscriptions
const pusherLink = new PusherLink({pusher: pusherClient})

// Combine the two links to work together
const link = ApolloLink.from([pusherLink, httpLink])

// Initialize the client
const client = new ApolloClient({
  link: link,
  cache: new InMemoryCache()
});

This link will check responses for the X-Subscription-ID header, and if it's present, it will use that value to subscribe to Pusher for future updates.

If you're using compressed payloads, configure a decompress: function, too:

// Add `pako` to the project for gunzipping
import pako from "pako"

const pusherLink = new PusherLink({
  pusher: pusherClient,
  decompress: function(compressed) {
    // Decode base64
    const data = atob(compressed)
      .split('')
      .map(x => x.charCodeAt(0));
    // Decompress
    const payloadString = pako.inflate(new Uint8Array(data), { to: 'string' });
    // Parse into an object
    return JSON.parse(payloadString);
  }
})

Apollo Link -- Ably Copy Chapter

graphql-ruby-client includes support for subscriptions with Ably and ApolloLink.

To use it, add AblyLink before your HttpLink.

For example:

// Load Apollo stuff
import { ApolloClient, HttpLink, ApolloLink, InMemoryCache } from '@apollo/client';
// Load Ably subscriptions link
import AblyLink from 'graphql-ruby-client/subscriptions/AblyLink'
// Load Ably and create a client
const Ably = require("ably")
const ablyClient = new Ably.Realtime({ key: "your-app-key" })

// Make the HTTP link which actually sends the queries
const httpLink = new HttpLink({
  uri: '/graphql',
  credentials: 'include'
});

// Make the Ably link which will pick up on subscriptions
const ablyLink = new AblyLink({ably: ablyClient})

// Combine the two links to work together
const link = ApolloLink.from([ablyLink, httpLink])

// Initialize the client
const client = new ApolloClient({
  link: link,
  cache: new InMemoryCache()
});

This link will check responses for the X-Subscription-ID header, and if it's present, it will use that value to subscribe to Ably for future updates.

For your app key, make a key with "Subscribe" and "Presence" privileges and use that:

Apollo Link -- ActionCable Copy Chapter

graphql-ruby-client includes support for subscriptions with ActionCable and ApolloLink.

To use it, construct a split link that routes:

• subscription queries to an ActionCableLink; and
• other queries to an HttpLink

For example:

import { ApolloClient, HttpLink, ApolloLink, InMemoryCache } from '@apollo/client';
import { createConsumer } from '@rails/actioncable';
import ActionCableLink from 'graphql-ruby-client/subscriptions/ActionCableLink';

const cable = createConsumer()

const httpLink = new HttpLink({
  uri: '/graphql',
  credentials: 'include'
});

const hasSubscriptionOperation = ({ query: { definitions } }) => {
  return definitions.some(
    ({ kind, operation }) => kind === 'OperationDefinition' && operation === 'subscription'
  )
}

const link = ApolloLink.split(
  hasSubscriptionOperation,
  new ActionCableLink({cable}),
  httpLink
);

const client = new ApolloClient({
  link: link,
  cache: new InMemoryCache()
});

Note that for Rails 5, the ActionCable client package is actioncable, not @rails/actioncable.

Apollo 1 Copy Chapter

graphql-ruby-client includes support for Apollo 1 client subscriptions over Pusher or ActionCable.

To use it, require subscriptions/addGraphQLSubscriptions and call the function with your network interface and transport client (example below).

See the Subscriptions guide for information about server-side setup.

Apollo 1 -- Pusher Copy Section

Pass {pusher: pusherClient} to use Pusher:

// Load Pusher and create a client
var Pusher = require("pusher-js")
var pusherClient = new Pusher(appKey, options)

// Add subscriptions to the network interface with the `pusher:` options
import addGraphQLSubscriptions from "graphql-ruby-client/subscriptions/addGraphQLSubscriptions"
addGraphQLSubscriptions(myNetworkInterface, {pusher: pusherClient})

// Optionally, add persisted query support:
var OperationStoreClient = require("./OperationStoreClient")
RailsNetworkInterface.use([OperationStoreClient.apolloMiddleware])

If you're using compressed payloads, configure a decompress: function, too:

// Add `pako` to the project for gunzipping
import pako from "pako"

addGraphQLSubscriptions(myNetworkInterface, {
  pusher: pusherClient,
  decompress: function(compressed) {
    // Decode base64
    const data = btoa(compressed)
    // Decompress
    const payloadString = pako.inflate(data, { to: 'string' })
    // Parse into an object
    return JSON.parse(payloadString);
  }
})

Apollo 1 -- ActionCable Copy Section

By passing {cable: cable}, all subscription queries will be routed to ActionCable.

For example:

// Load ActionCable and create a consumer
var ActionCable = require('@rails/actioncable')
var cable = ActionCable.createConsumer()
window.cable = cable

// Load ApolloClient and create a network interface
var apollo = require('apollo-client')
var RailsNetworkInterface = apollo.createNetworkInterface({
 uri: '/graphql',
 opts: {
   credentials: 'include',
 },
 headers: {
   'X-CSRF-Token': $("meta[name=csrf-token]").attr("content"),
 }
});

// Add subscriptions to the network interface
import addGraphQLSubscriptions from "graphql-ruby-client/subscriptions/addGraphQLSubscriptions"
addGraphQLSubscriptions(RailsNetworkInterface, {cable: cable})

// Optionally, add persisted query support:
var OperationStoreClient = require("./OperationStoreClient")
RailsNetworkInterface.use([OperationStoreClient.apolloMiddleware])

Guides Javascript Client Graphiql Subscriptions (`guides/javascript_client/graphiql_subscriptions.md`) Copy Section

GraphiQL Subscriptions

After setting up your server, you can integrate subscriptions into GraphiQL, the in-browser GraphQL IDE.

Adding GraphiQL to your app Copy Chapter

To get started, make a page for rendering GraphiQL, for example:

<div id="root" style="height: 100vh;"></div>

Then, install GraphiQL (eg, yarn add graphiql) and add JavaScript code to import GraphiQL and render it on your page:

import { GraphiQL } from 'graphiql'
import React from 'react'
import { createRoot } from 'react-dom/client'
import 'graphiql/graphiql.css'
import { createGraphiQLFetcher } from '@graphiql/toolkit'

const fetcher = createGraphiQLFetcher({ url: '/graphql' })
const root = createRoot(document.getElementById('root'))
root.render(<GraphiQL fetcher={fetcher}/>)

After that, you should be able to load the page in your app and see the GraphiQL editor.

Ably Copy Chapter

To integrate Ably subscriptions, use createAblyFetcher, for example:

import Ably from "ably"
import createAblyFetcher from 'graphql-ruby-client/subscriptions/createAblyFetcher'

// Initialize a client
// the key must have "subscribe" and "presence" permissions
const ably = new Ably.Realtime({ key: "your.application.key" })

// Initialize a new fetcher and pass it to GraphiQL below
var fetcher = createAblyFetcher({ ably: ably, url: "/graphql" })
const root = createRoot(document.getElementById('root'))
root.render(<GraphiQL fetcher={fetcher} />)

Under the hood, it will use window.fetch to send GraphQL operations to the server, then listen for X-Subscription-ID headers in responses. To customize its HTTP requests, you can pass a fetchOptions: object or a custom fetch: function to createAblyFetcher({ ... }).

Pusher Copy Chapter

To integrate Pusher subscriptions, use createPusherFetcher, for example:

import Pusher from "pusher-js"
import createPusherFetcher from 'graphql-ruby-client/subscriptions/createPusherFetcher'

// Initialize a client
const pusher = new Pusher("your-app-key", { cluster: "your-cluster" })

// Initialize a new fetcher and pass it to GraphiQL below
var fetcher = createPusherFetcher({ pusher: pusher, url: "/graphql" })
const root = createRoot(document.getElementById('root'))
root.render(<GraphiQL fetcher={fetcher} />)

Under the hood, it will use window.fetch to send GraphQL operations to the server, then listen for X-Subscription-ID headers in responses. To customize its HTTP requests, you can pass a fetchOptions: object or a custom fetch: function to createPusherFetcher({ ... }).

ActionCable Copy Chapter

To integrate ActionCable subscriptions, use createActionCableFetcher, for example:

import { createConsumer } from "@rails/actioncable"
import createActionCableFetcher from 'graphql-ruby-client/subscriptions/createActionCableFetcher';

// Initialize a client
const actionCable = createConsumer()

// Initialize a new fetcher and pass it to GraphiQL below
var fetcher = createActionCableFetcher({ consumer: actionCable, url: "/graphql" })
const root = createRoot(document.getElementById('root'))
root.render(<GraphiQL fetcher={fetcher} />)

Under the hood, it will split traffic: it will send subscription { ... } operations via ActionCable and send queries and mutations via HTTP POST using window.fetch. To customize its HTTP requests, you can pass a fetchOptions: object or a custom fetch: function to createActionCableFetcher({ ... }).

Guides Javascript Client Relay Subscriptions (`guides/javascript_client/relay_subscriptions.md`) Copy Section

Relay Subscriptions

graphql-ruby-client includes three kinds of support for subscriptions with Relay Modern:

• Pusher
• Ably
• ActionCable

To use it, require graphql-ruby-client/subscriptions/createRelaySubscriptionHandler and call the function with your client and optionally, your OperationStoreClient.

Note: For Relay <11, use import { createLegacyRelaySubscriptionHandler } from "graphql-ruby-client/subscriptions/createRelaySubscriptionHandler" instead; the signature changed in Relay 11.

See the Subscriptions guide for information about server-side setup.

Pusher Copy Chapter

Subscriptions with Pusher require two things:

• A client from the pusher-js library
• A fetchOperation function for sending the subscription operation to the server

Pusher client Copy Section

Pass pusher: to get Subscription updates over Pusher:

// Load the helper function
import createRelaySubscriptionHandler from "graphql-ruby-client/subscriptions/createRelaySubscriptionHandler"

// Prepare a Pusher client
var Pusher = require("pusher-js")
var pusherClient = new Pusher(appKey, options)

// Create a fetchOperation, see below for more details
function fetchOperation(operation, variables, cacheConfig) {
  return fetch(...)
}

// Create a Relay Modern-compatible handler
var subscriptionHandler = createRelaySubscriptionHandler({
  pusher: pusherClient,
  fetchOperation: fetchOperation
})

// Create a Relay Modern network with the handler
var network = Network.create(fetchQuery, subscriptionHandler)

Compressed Payloads Copy Section

If you're using compressed payloads, configure a decompress: function, too:

// Add `pako` to the project for gunzipping
import pako from "pako"

var subscriptionHandler = createRelaySubscriptionHandler({
  pusher: pusherClient,
  fetchOperation: fetchOperation,
  decompress: function(compressed) {
    // Decode base64
    const data = btoa(compressed)
    // Decompress
    const payloadString = pako.inflate(data, { to: 'string' })
    // Parse into an object
    return JSON.parse(payloadString);
  }
})

Ably Copy Chapter

Subscriptions with Ably require two things:

• A client from the ably-js library
• A fetchOperation function for sending the subscription operation to the server

Ably client Copy Section

Pass ably: to get Subscription updates over Ably:

// Load the helper function
import createRelaySubscriptionHandler from "graphql-ruby-client/subscriptions/createRelaySubscriptionHandler"

// Load Ably and create a client
const Ably = require("ably")
const ablyClient = new Ably.Realtime({ key: "your-app-key" })

// create a fetchOperation, see below for more details
function fetchOperation(operation, variables, cacheConfig) {
  return fetch(...)
}

// Create a Relay Modern-compatible handler
var subscriptionHandler = createRelaySubscriptionHandler({
  ably: ablyClient,
  fetchOperation: fetchOperation
})

// Create a Relay Modern network with the handler
var network = Network.create(fetchQuery, subscriptionHandler)

ActionCable Copy Chapter

With this configuration, subscription queries will be routed to ActionCable.

For example:

// Require the helper function
import createRelaySubscriptionHandler from "graphql-ruby-client/subscriptions/createRelaySubscriptionHandler")
// Optionally, load your OperationStoreClient
var OperationStoreClient = require("./OperationStoreClient")

// Create a Relay Modern-compatible handler
var subscriptionHandler = createRelaySubscriptionHandler({
  cable: createConsumer(...),
  operations: OperationStoreClient,
})

// Create a Relay Modern network with the handler
var network = Network.create(fetchQuery, subscriptionHandler)

With Relay Persisted Queries Copy Chapter

If you're using Relay's built-in persisted query support, you can pass clientName: to the handler in order to build IDs that work with the OperationStore. For example:

var subscriptionHandler = createRelaySubscriptionHandler({
  cable: createConsumer(...),
  clientName: "web-frontend", // This should match the one you use for `sync`
})

// Create a Relay Modern network with the handler
var network = Network.create(fetchQuery, subscriptionHandler)

Then, the ActionCable handler will use Relay's provided operation IDs to interact with the OperationStore.

fetchOperation function Copy Chapter

The fetchOperation function can be extracted from your fetchQuery function. Its signature is:

// Returns a promise from `fetch`
function fetchOperation(operation, variables, cacheConfig) {
  return fetch(...)
}

• operation, variables, and cacheConfig are the first three arguments to the fetchQuery function.
• The function should call fetch and return the result (a Promise of a Response).

For example, Environment.js may look like:

// This function sends a GraphQL query to the server
const fetchOperation = function(operation, variables, cacheConfig) {
  const bodyValues = {
    variables,
    operationName: operation.name,
  }
  const useStoredOperations = process.env.NODE_ENV === "production"
  if (useStoredOperations) {
    // In production, use the stored operation
    bodyValues.operationId = OperationStoreClient.getOperationId(operation.name)
  } else {
    // In development, use the query text
    bodyValues.query = operation.text
  }
  return fetch('http://localhost:3000/graphql', {
    method: 'POST',
    opts: {
      credentials: 'include',
    },
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(bodyValues),
  })
}

// `fetchQuery` uses `fetchOperation`, but returns a Promise of JSON
const fetchQuery = (operation, variables, cacheConfig, uploadables) => {
  return fetchOperation(operation, variables, cacheConfig).then(response => {
    return response.json()
  })
}

// Subscriptions uses the same `fetchOperation` function for initial subscription requests
const subscriptionHandler = createRelaySubscriptionHandler({pusher: pusherClient, fetchOperation: fetchOperation})
// Combine them into a `Network`
const network = Network.create(fetchQuery, subscriptionHandler)

Since OperationStoreClient is in the fetchOperation function, it will apply to all GraphQL operations.

Guides Javascript Client Sync (`guides/javascript_client/sync.md`) Copy Section

OperationStore Sync

JavaScript support for GraphQL projects using graphql-pro's OperationStore for persisted queries.

• sync CLI
• Relay <2 support
• Relay 2+ support
• Apollo Client support
• Apollo Link support
• Apollo Codegen Support
• Apollo Android support
• Apollo Persisted Queries Support
• Plain JS support
• Authorization

See the OperationStore guide for server-side setup.

`sync` utility Copy Chapter

This package contains a command line utility, graphql-ruby-client sync:

$ graphql-ruby-client sync # ...
Authorizing with HMAC
Syncing 4 operations to http://myapp.com/graphql/operations...
  3 added
  1 not modified
  0 failed
Generating client module in app/javascript/graphql/OperationStoreClient.js...
✓ Done!

sync Takes several options:

You can see these and a few others with graphql-ruby-client sync --help.

Use with Relay <2 Copy Chapter

graphql-ruby-client can persist queries from relay-compiler using the embedded @relayHash value. (This was created in Relay before 2.0.0. See below for Relay 2.0+.)

To sync your queries with the server, use the --path option to point to your __generated__ directory, for example:

# sync a Relay project
$ graphql-ruby-client sync --path=src/__generated__  --outfile=src/OperationStoreClient.js --url=...

Then, the generated code may be integrated with Relay's Network Layer:

// ...
// require the generated module:
const OperationStoreClient = require('./OperationStoreClient')

// ...
function fetchQuery(operation, variables, cacheConfig, uploadables) {
  const requestParams = {
    variables,
    operationName: operation.name,
  }

  if (process.env.NODE_ENV === "production")
    // In production, use the stored operation
    requestParams.operationId = OperationStoreClient.getOperationId(operation.name)
  } else {
    // In development, use the query text
    requestParams.query = operation.text,
  }

  return fetch('/graphql', {
    method: 'POST',
    headers: { /*...*/ },
    body: JSON.stringify(requestParams),
  }).then(/* ... */);
}

// ...

(Only Relay Modern is supported. Legacy Relay can't generate static queries.)

Use With Relay Persisted Output Copy Chapter

To use Relay's persisted output, add a "file": ... to your project's persistConfig object. For example:

"relay": {
    ...
    "persistConfig": {
      "file": "./persisted-queries.json"
    }
  },

Then, push Relay's generated queries to your OperationStore server with --relay-persisted-output:

$ graphql-ruby-client sync --relay-persisted-output=path/to/persisted-queries.json --url=...

In this case, sync won't generate a JavaScript module because relay-compiler has already prepared its queries for persisted use. Instead, update your network layer to include the client name and operation id in the HTTP params:

const operationStoreClientName = "MyRelayApp";

function fetchQuery(operation, variables,) {
  return fetch('/graphql', {
    method: 'POST',
    headers: {
      'content-type': 'application/json'
    },
    body: JSON.stringify({
      // Pass the client name and the operation ID, joined by `/`
      documentId: operationStoreClientName + "/" + operation.id,
      // query: operation.text, // this is now obsolete because text is null
      variables,
    }),
  }).then(response => {
    return response.json();
  });
}

(Inspired by https://relay.dev/docs/guides/persisted-queries/#network-layer-changes.)

Now, your Relay app will only send operation IDs over the wire to the server.

Use with Apollo Client Copy Chapter

Use the --path option to point at your .graphql files:

$ graphql-ruby-client sync --path=src/graphql/ --url=...

Then, load the generated module and add its .apolloMiddleware to your network interface with .use([...]):

// load the generated module
var OperationStoreClient = require("./OperationStoreClient")

// attach it as middleware in production
// (in development, send queries to the server as normal)
if (process.env.NODE_ENV === "production") {
  MyNetworkInterface.use([OperationStoreClient.apolloMiddleware])
}

Now, the middleware will replace query strings with operationIds.

Use with Apollo Link Copy Chapter

Use the --path option to point at your .graphql files:

$ graphql-ruby-client sync --path=src/graphql/ --url=...

Then, load the generated module and add its .apolloLink to your Apollo Link:

// load the generated module
var OperationStoreClient = require("./OperationStoreClient")

// Integrate the link to another link:
const link = ApolloLink.from([
  authLink,
  OperationStoreClient.apolloLink,
  httpLink,
])

// Create a client
const client = new ApolloClient({
  link: link,
  cache: new InMemoryCache(),
});

Update the controller: Apollo Link supports extra parameters nested as params[:extensions][:operationId], so update your controller to add that param to context:

# app/controllers/graphql_controller.rb
context = {
  # ...
  # Support Apollo Link:
  operation_id: params[:extensions][:operationId]
}

Now, context[:operation_id] will be used to fetch a query from the database.

Use with Apollo Codegen Copy Chapter

Use apollo client:codegen ... --target json to build a JSON artifact containing your app's queries. Then, pass the path to that artifact to graphql-ruby-client sync --apollo-codegen-json-output path/to/output.json .... sync will use Apollo-generated operationIds to populate the OperationStore.

Then, to use Apollo-style persisted query IDs, hook up the Persisted Queries Link as described in Apollo's documentation

Finally, update the controller to pass the Apollo-style persisted query ID as the operation ID:

# app/controllers/graphql_controller.rb
context = {
  # ...
  # Support already-synced Apollo Persisted Queries:
  operation_id: params[:extensions][:operationId]
}

Now, Apollo-style persisted query IDs will be used to fetch operations from the server's OperationStore.

Use with Apollo Android Copy Chapter

Apollo Android's generateOperationOutput option builds an OperationOutput.json file which works with the OperationStore. To sync those queries, use the --apollo-android-operation-output option:

graphql-ruby-client sync --apollo-android-operation-output=path/to/OperationOutput.json --url=...

That way, the OperationStore will use the query IDs generated by Apollo Android.

On the server, you'll have to update your controller to receive the client name and the operation ID. For example:

# app/controllers/graphql_controller.rb
context = { ... }

# Check for an incoming operation ID from Apollo Client:
apollo_android_operation_id = request.headers["X-APOLLO-OPERATION-ID"]
if apollo_android_operation_id.present?
  # Check the incoming request to confirm that
  # it's your first-party client with stored operations
  client_name = # ...
  if client_name.present?
    # If we received an incoming operation ID
    # _and_ identified the client, run a persisted operation.
    context[:operation_id] = "#{client_name}/#{apollo_android_operation_id}"
  end
end

You may also have to update your app to send an identifier, so that the server can determine the "client name" used with the operation store. (Apollo Android sends a query hash, but the operation store expects IDs in the form #{client_name}/#{query_hash}.)

Use with Apollo Persisted Queries Copy Chapter

Apollo client has a Persisted Queries Link. You can use that link with GraphQL-Pro's OperationStore. First, create a manifest with generate-persisted-query-manifest, then, pass the path to that file to sync:

$ graphql-ruby-client sync --apollo-persisted-query-manifest=path/to/manifest.json ...

Then, configure Apollo Client to use your persisted query manifest.

Finally, update your controller to receive the operation ID and pass it as context[:operation_id]:

client_name = "..." # TODO: send the client name as a query param or header
persisted_query_hash = params[:extensions][:persistedQuery][:sha256Hash]
context = {
  # ...
  operation_id: "#{client_name}/#{persisted_query_hash}"
}

The operation_id will also need your client name. Using Apollo Client, you could send this as a custom header or another way that works for your application (eg, session or user agent).

Use with plain JavaScript Copy Chapter

OperationStoreClient.getOperationId takes an operation name as input and returns the server-side alias for that operation:

var OperationStoreClient = require("./OperationStoreClient")

OperationStoreClient.getOperationId("AppHomeQuery")       // => "my-frontend-app/7a8078c7555e20744cb1ff5a62e44aa92c6e0f02554868a15b8a1cbf2e776b6f"
OperationStoreClient.getOperationId("ProductDetailQuery") // => "my-frontend-app/6726a3b816e99b9971a1d25a1205ca81ecadc6eb1d5dd3a71028c4b01cc254c1"

Post the operationId in your GraphQL requests:

// Lookup the operation name:
var operationId = OperationStoreClient.getOperationId(operationName)

// Include it in the params:
$.post("/graphql", {
  operationId: operationId,
  variables: queryVariables,
}, function(response) {
  // ...
})

Authorization Copy Chapter

OperationStore uses HMAC-SHA256 to authenticate requests.

Pass the key to graphql-ruby-client sync as --secret to authenticate it:

$ export MY_SECRET_KEY= "abcdefg..."
$ graphql-ruby-client sync ... --secret=$MY_SECRET_KEY
# ...
Authenticating with HMAC
# ...

Guides Javascript Client Urql Subscriptions (`guides/javascript_client/urql_subscriptions.md`) Copy Section

urql Subscriptions

GraphQL-Ruby currently supports using urql with the ActionCable and Pusher implementation.

Pusher Copy Chapter

import SubscriptionExchange from "graphql-ruby-client/subscriptions/SubscriptionExchange"
import Pusher from "pusher"
import { Client, defaultExchanges, subscriptionExchange } from 'urql'

const pusherClient = new Pusher("your-app-key", { cluster: "us2" })
const forwardToPusher = SubscriptionExchange.create({ pusher: pusherClient })

const client = new Client({
  url: '/graphql',
  exchanges: [
    ...defaultExchanges,
    subscriptionExchange({
      forwardSubscription: forwardToPusher
    }),
  ],
});

ActionCable Copy Chapter

import { createConsumer } from "@rails/actioncable";
import SubscriptionExchange from "graphql-ruby-client/subscriptions/SubscriptionExchange"

const actionCable = createConsumer('ws://127.0.0.1:3000/cable');
const forwardToActionCable = SubscriptionExchange.create({ consumer: actionCable })

const client = new Client({
  url: '/graphql',
  exchanges: [
    ...defaultExchanges,
    subscriptionExchange({
      forwardSubscription: forwardToActionCable
    }),
  ],
});

Want to use urql with another subscription backend? Please open an issue.

Guides Language Tools C Parser (`guides/language_tools/c_parser.md`) Copy Section

C-based Parser

GraphQL-Ruby includes a plain-Ruby parser, but a faster parser is available as a C extension. To use it, add the graphql-c_parser gem to your project, for example:

bundle add graphql-c_parser

When graphql-c_parser is required by your app, the C-based parser is installed as the default parser (as GraphQL.default_parser). Bundler requires the library automatically, but you can also require it manually:

require "graphql/c_parser"

This alternative parser is faster and uses less memory.

The library also adds GraphQL.scan_with_c and GraphQL.parse_with_c for calling the C-based parser directly.

Guides Language Tools Visitor (`guides/language_tools/visitor.md`) Copy Section

AST Visitor

GraphQL code is usually contained in a string, for example:

query_string = "query { user(id: \"1\") { userName } }"

You can perform programmatic analysis and modifications to GraphQL code using a three-step process:

• Parse the code into an abstract syntax tree
• Analyze/Modify the code with a visitor
• Print the code back to a string

Parse Copy Chapter

GraphQL.parse turns a string into a GraphQL document:

parsed_doc = GraphQL.parse("{ user(id: \"1\") { userName } }")
# => #<GraphQL::Language::Nodes::Document ...>

Also, GraphQL.parse_file parses the contents of the named file and includes a filename in the parsed document.

AST Nodes

The parsed document is a tree of nodes, called an abstract syntax tree (AST). This tree is immutable: once a document has been parsed, those Ruby objects can't be changed. Modifications are performed by copying existing nodes, applying changes to the copy, then making a new tree to hold the copied node. Where possible, unmodified nodes are retained in the new tree (it's persistent).

The copy-and-modify workflow is supported by a few methods on the AST nodes:

• .merge(new_attrs) returns a copy of the node with new_attrs applied. This new copy can replace the original node.
• .add_{child}(new_child_attrs) makes a new node with new_child_attrs, adds it to the array specified by {child}, and returns a copy whose {children} array contains the newly created node.

For example, to rename a field and add an argument to it, you could:

modified_node = field_node
  # Apply a new name
  .merge(name: "newName")
  # Add an argument to this field's arguments
  .add_argument(name: "newArgument", value: "newValue")

Above, field_node is unmodified, but modified_node reflects the new name and new argument.

Analyze/Modify Copy Chapter

To inspect or modify a parsed document, extend GraphQL::Language::Visitor and implement its various hooks. It's an implementation of the visitor pattern. In short, each node of the tree will be "visited" by calling a method, and those methods can gather information and perform modifications.

In the visitor, each node class has a hook, for example:

• GraphQL::Language::Nodes::Fields are routed to #on_field
• GraphQL::Language::Nodes::Arguments are routed to #on_argument

See the GraphQL::Language::Visitor API docs for a full list of methods.

Each method is called with (node, parent), where:

• node is the AST node currently visited
• parent is the AST node above this node in the tree

The method has a few options for analyzing or modifying the AST:

Continue/Halt

To continue visiting, the hook should call super. This allows the visit to continue to node's children in the tree, for example:

def on_field(_node, _parent)
  # Do nothing, this is the default behavior:
  super
end

To halt the visit, a method may skip the call to super. For example, if the visitor encountered an error, it might want to return early instead of continuing to visit.

Modify a Node

Visitor hooks are expected to return the (node, parent) they are called with. If they return a different node, then that node will replace the original node. When you call super(node, parent), the node is returned. So, to modify a node and continue visiting:

• Make a modified copy of node
• Pass the modified copy to super(new_node, parent)

For example, to rename an argument:

def on_argument(node, parent)
  # make a copy of `node` with a new name
  modified_node = node.merge(name: "renamed")
  # continue visiting with the modified node and parent
  super(modified_node, parent)
end

Delete a Node

To delete the currently-visited node, don't pass node to super(...). Instead, pass a magic constant, DELETE_NODE, in place of node.

For example, to delete a directive:

def on_directive(node, parent)
  # Don't pass `node` to `super`,
  # instead, pass `DELETE_NODE`
  super(DELETE_NODE, parent)
end

Insert a Node

Inserting nodes is similar to modifying nodes. To insert a new child into node, call one of its .add_ helpers. This returns a copied node with a new child added. For example, to add a selection to a field's selection set:

def on_field(node, parent)
  node_with_selection = node.add_selection(name: "emailAddress")
  super(node_with_selection, parent)
end

This will add emailAddress the fields selection on node.

(These .add_* helpers are wrappers around GraphQL::Language::Nodes::AbstractNode#merge.)

Print Copy Chapter

The easiest way to turn an AST back into a string of GraphQL is GraphQL::Language::Nodes::AbstractNode#to_query_string, for example:

parsed_doc.to_query_string
# => '{ user(id: "1") { userName } }'

You can also create a subclass of GraphQL::Language::Printer to customize how nodes are printed.

Guides Limiters Active Operations (`guides/limiters/active_operations.md`) Copy Section

Active Operation Limiter

GraphQL::Enterprise::ActiveOperationLimiter prevents clients from running too many GraphQL operations at the same time. It uses Redis to track currently-running operations.

Why? Copy Chapter

Some clients may suddently swamp a server with tons of requests, occupying all available Ruby processes and therefore interrupting service for other clients. This limiter aims to prevent that at the GraphQL level by halting queries when a client already has lots of queries running. That way, server processes will remain available for other clients' requests.

Setup Copy Chapter

To use this limiter, update the schema configuration and include context[:limiter_key] in your queries.

Schema Setup

To setup the schema, add use GraphQL::Enterprise::ActiveOperationLimiter with a default limit: value:

class MySchema < GraphQL::Schema
  # ...
  use GraphQL::Enterprise::ActiveOperationLimiter,
    redis: Redis.new(...),
    # Or:
    # connection_pool: ...
    # redis_cluster: ...
    limit: 5
end

limit: false may also be given, which defaults to no limit for this limiter.

It also accepts a stale_request_seconds: option. The limiter uses that value to clean up request data in case of a crash or other unexpected scenario.

Before requests will actually be halted, soft mode must be disabled.

Query Setup

In order to limit clients, the limiter needs a client identifier for each GraphQL operation. By default, it checks context[:limiter_key] to find it:

context = {
  viewer: current_user,
  # for example:
  limiter_key: logged_in? ? "user:#{current_user.id}" : "anon-ip:#{request.remote_ip}",
  # ...
}

result = MySchema.execute(query_str, context: context)

Operations with the same context[:limiter_key] will rate limited in the same buckets. A limiter key is required; if a query is run without one, the limiter will raise an error.

To provide a client identifier another way, see Customization.

Customization Copy Chapter

GraphQL::Enterprise::ActiveOperationLimiter provides several hooks for customizing its behavior. To use these, make a subclass of the limiter and override methods as described:

# app/graphql/limiters/active_operations.rb
class Limiters::ActiveOperations < GraphQL::Enterprise::ActiveOperationsLimiter
  # override methods here
end

The hooks are:

• def limiter_key(query) should return a string which identifies the current client for query.
• def limit_for(key, query) should return an integer or nil. If an integer is returned, that limit is applied for the current query. If nil is returned, no limit is applied to the current query.
• def soft_limit?(key, query) can be implemented to customize the application of "soft mode". By default, it checks a setting in redis.
• def handle_redis_error(err) is called when the limit rescues an error from Redis. By default, it's passed to warn and the query is not halted.

Instrumentation Copy Chapter

While the limiter is installed, it adds some information to the query context about its operation. It can be accessed at context[:active_operation_limiter]:

result = MySchema.execute(...)

pp result.context[:active_operation_limiter]
# {:key=>"user:123", :limit=>2, :soft=>false, :limited=>true}

It returns a Hash containing:

• key: [String], the limiter key used for this query
• limit: [Integer, nil], the limit applied to this query
• soft: [Boolean], true if the query was run in "soft mode"
• limited: [Boolean], true if the query exceeded the rate limit (but if soft: was also true, then the query was not halted)

You could use this to add detailed metrics to your application monitoring system, for example:

MyMetrics.increment("graphql.active_operation_limiter", tags: result.context[:active_operation_limiter])

Guides Limiters Deployment (`guides/limiters/deployment.md`) Copy Section

Deploying Rate Limiters

Here are a few options for deploying GraphQL-Enterprise's rate limiters:

• The Dashboard shows some basic metrics about the limiter.
• Soft limits start logging over-limit requests to the dashboard but don't actually halt traffic.
• Subscriptions need extra consideration

Dashboard Copy Chapter

Once installed, your GraphQL-Pro dashboard will include a simple metrics view:

To disable dashboard charts, add use(... dashboard_charts: false) to your configuration.

Also, the dashboard includes a link to enable or disable "soft mode":

When "soft mode" is enabled, limited requests are not actually halted (although they are counted). When "soft mode" is disabled, any over-limit requests are halted.

For more detailed metrics, see the "Instrumentation" section of the documentation for each limiter.

Soft Limits Copy Chapter

By default, limiters don't actually halt queries; instead, they start out in "soft mode". In this mode:

• limited/unlimited requests are counted in the Dashboard
• but, no requests are actually halted

This mode is for assessing the impact of the limiter before it's applied to production traffic. Additionally, if you release the limiter but find that it's affecting production traffic adversely, you can re-enable "soft mode" to stop blocking traffic.

To disable "soft mode" and start limiting, use the Dashboard or re-implement some of the customization methods of the limiter.

You can also disable "soft mode" in Ruby:

# Turn "soft mode" off for the ActiveOperationLimiter
MySchema.enterprise_active_operation_limiter.set_soft_limit(false)
# or, for RuntimeLimiter
MySchema.enterprise_runtime_limiter.set_soft_limit(false)

Subscriptions Copy Chapter

If you're using PusherSubscriptions or AblySubscriptions, then you'll need to accomodate subscriptions that were created before you deployed the rate limiter. Those subscriptions are already stored in Redis and their contexts don't include the required limiter_key: value.

To address this, you can customize the limiter(s) you're using to provide a default value in this case. For example:

class CustomRuntimeLimiter < GraphQL::Enterprise::RuntimeLimiter
  def limiter_key(query)
    if query.subscription_update? && query.context[:limiter_key].nil?
      # This subscription was created before limiter_key was required,
      # so provide a value for it.
      # If `context` includes enough information to create a
      # "real" limiter key, you could also do that here.
      # In this case, we're providing a default flag:
      "legacy-subscription-update"
    else
      super
    end
  end

  def limit_for(key, query)
    if key == "legacy-subscription-update"
      nil # no limit in this case
    else
      super
    end
  end
end

With methods like that, any subscriptions created before limiter_key: was required will not be subject to rate limits. Adjust those methods as needed for your application. Finally, be sure to attach your custom limiter in your schema, for example:

# Use a custom subclass of GraphQL::Enterprise::RuntimeLimiter:
use CustomRuntimeLimiter, ...

Guides Limiters Redis (`guides/limiters/redis.md`) Copy Section

Configuring Redis

Rate limiting requires a persistent Redis instance, just like Sidekiq or the Operation Store. Set maxmemory-policy noeviction in redis.conf to ensure that Redis doesn't silently drop keys when it reaches its memory limit.

Memory Usage Copy Chapter

Estimating memory usage depends on the string used to identify clients, since those are used in the Redis keys. Using 100-character client keys, the runtime limiter uses 400 bytes per client (two keys). Memory usage by the active operation limiter depends on the limit because each concurrent operation uses some memory; a higher limit permits more concurrent operations. With 10 active operations and a 100-character client key, the active operation limiter uses 350 bytes per client. Additionally, the limiters use up to 35kb for dashboards (2 limiters, for each one: 2x 60 per-minute keys, 24 hourly keys, and 30 daily keys @ 72 bytes per key).

By those estimates, 1 gigabyte of memory would support both rate limiters for over 1.4 million active clients.

Connection Pool Copy Chapter

ActiveOperationsLimiter and RuntimeLimiter support ConnectionPool. To use it, pass connection_pool::

use GraphQL::Enterprise::RuntimeLimiter, # or ActiveOperationLimiter
  connection_pool: ConnectionPool.new(...) { ... }
  # ...

Redis Cluster Copy Chapter

ActiveOperationsLimiter and RuntimeLimiter support redis-cluster. To use it, pass redis_cluster::

use GraphQL::Enterprise::RuntimeLimiter, # or ActiveOperationLimiter
  redis_cluster: Redis::Cluster.new(...)
  # ...

Guides Limiters Runtime (`guides/limiters/runtime.md`) Copy Section

Runtime Limiter

GraphQL::Enterprise::RuntimeLimiter applies an upper bound to processing time consumed by a single client. It uses Redis track time with a token bucket algorithm.

Why? Copy Chapter

This limiter prevents a single client from consuming too much processing time, regardless of whether it comes a burst of short-lived queries (which the Active Operation Limiter can prevent) or a small number of long-running queries. Unlike request counters or complexity calculations, the runtime limiter pays no attention to the structure of the incoming request. Instead, it simply measures the time spent on the request as a whole and halts queries when a client consumes more than the limit.

Setup Copy Chapter

To use this limiter, update the schema configuration and include context[:limiter_key] in your queries.

Schema Setup Copy Section

To setup the schema, add use GraphQL::Enterprise::RuntimeLimiter with a default limit_ms: value:

class MySchema < GraphQL::Schema
  # ...
  use GraphQL::Enterprise::RuntimeLimiter,
    redis: Redis.new(...),
    # Or:
    # connection_pool: ...
    # redis_cluster: ...
    limit_ms: 90 * 1000 # 90 seconds per minute
end

limit_ms: false may also be given, which defaults to no limit for this limiter.

It also accepts a window_ms: option, which is the duration over which limit_ms: is added to a client's bucket. It defaults to 60_000 (one minute).

Before requests will actually be halted, soft mode must be disabled.

Query Setup Copy Section

In order to limit clients, the limiter needs a client identifier for each GraphQL operation. By default, it checks context[:limiter_key] to find it:

context = {
  viewer: current_user,
  # for example:
  limiter_key: logged_in? ? "user:#{current_user.id}" : "anon-ip:#{request.remote_ip}",
  # ...
}

result = MySchema.execute(query_str, context: context)

Operations with the same context[:limiter_key] will rate limited in the same buckets. A limiter key is required; if a query is run without one, the limiter will raise an error.

To provide a client identifier another way, see Customization.

Customization Copy Chapter

GraphQL::Enterprise::RuntimeLimiter provides several hooks for customizing its behavior. To use these, make a subclass of the limiter and override methods as described:

# app/graphql/limiters/runtime.rb
class Limiters::Runtime < GraphQL::Enterprise::RuntimeLimiter
  # override methods here
end

The hooks are:

• def limiter_key(query) should return a string which identifies the current client for query.
• def limit_for(key, query) should return an integer or nil. If an integer is returned, that limit is applied for the current query. If nil is returned, no limit is applied to the current query.
• def soft_limit?(key, query) can be implemented to customize the application of "soft mode". By default, it checks a setting in redis.
• def handle_redis_error(err) is called when the limit rescues an error from Redis. By default, it's passed to warn and the query is not halted.

Instrumentation Copy Chapter

While the limiter is installed, it adds some information to the query context about its operation. It can be accessed at context[:runtime_limiter]:

result = MySchema.execute(...)

pp result.context[:runtime_limiter]
# {:key=>"custom-key-9",
#  :limit_ms=>800,
#  :remaining_ms=>0,
#  :soft=>true,
#  :limited=>true,
#  :window_ms=>60_000}

It returns a Hash containing:

• key: [String], the limiter key used for this query
• limit_ms: [Integer, nil], the limit applied to this query
• remaining_ms: [Integer, nil], the amount of time remaining in this client's bucket
• soft: [Boolean], true if the query was run in "soft mode"
• limited: [Boolean], true if the query exceeded the rate limit (but if soft: was also true, then the query was not halted)
• window_ms: [Integer] the configured window_ms: for the limiter

You could use this to add detailed metrics to your application monitoring system, for example:

MyMetrics.increment("graphql.runtime_limiter", tags: result.context[:runtime_limiter])

Some Caveats Copy Chapter

The limiter will not interrupt a long-running field. Instead, it stops executing new fields after a client exceeds its allowed processing time. This is because interrupting arbitrary code may have unintended consequences for I/O operations, see "Timeout: Ruby's most dangerous API".

Also, the limiter only checks remaining time at the start of a query and it only decreases the remaining time at the end of a query. This means that simulaneous queries may consume the remainder at the same time. Use the Active Operation Limiter to limit behavior in this regard. This implementation is basically a trade-off: more granular updates would require more communication with Redis which would add overhead to each request.

Guides Mutations Mutation Authorization (`guides/mutations/mutation_authorization.md`) Copy Section

Mutation authorization

Before running a mutation, you probably want to do a few things:

• Make sure the current user has permission to try this mutation
• Load some objects from the database, using some ID inputs
• Check if the user has permission to modify those loaded objects

This guide describes how to accomplish that workflow with GraphQL-Ruby.

Checking conditions before instantiating the mutation Copy Chapter

class UpdateUserMutation < BaseMutation
  # ...

  def resolve(update_user_input:, user:)
    # ...
  end

  def self.authorized?(obj, ctx)
    super && ctx[:viewer].present?
  end
end

Checking the user permissions Copy Chapter

Before loading any data from the database, you might want to see if the user has a certain permission level. For example, maybe only .admin? users can run Mutation.promoteEmployee.

This check can be implemented using the #ready? method in a mutation:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  def ready?(**args)
    # Called with mutation args.
    # Use keyword args such as employee_id: or **args to collect them
    if !context[:current_user].admin?
      raise GraphQL::ExecutionError, "Only admins can run this mutation"
    else
      # Return true to continue the mutation:
      true
    end
  end

  # ...
end

Now, when any non-admin user tries to run the mutation, it won't run. Instead, they'll get an error in the response.

Additionally, #ready? may return false, { ... } to return errors as data:

def ready?
  if !context[:current_user].allowed?
    return false, { errors: ["You don't have permission to do this"]}
  else
    true
  end
end

Loading and authorizing objects Copy Chapter

Often, mutations take IDs as input and use them to load records from the database. GraphQL-Ruby can load IDs for you when you provide a loads: option.

In short, here's an example:

class Mutations::PromoteEmployee < Mutations::BaseMutation
  # `employeeId` is an ID, Types::Employee is an _Object_ type
  argument :employee_id, ID, loads: Types::Employee

  # Behind the scenes, `:employee_id` is used to fetch an object from the database,
  # then the object is authorized with `Employee.authorized?`, then
  # if all is well, the object is injected here:
  def resolve(employee:)
    employee.promote!
  end
end

It works like this: if you pass a loads: option, it will:

• Automatically remove _id from the name and pass that name for the as: option
• Add a prepare hook to fetch an object with the given ID (using Schema.object_from_id)
• Check that the fetched object's type matches the loads: type (using Schema.resolve_type)
• Run the fetched object through its type's .authorized? hook (see Authorization)
• Inject it into #resolve using the object-style name (employee:)

In this case, if the argument value is provided by object_from_id doesn't return a value, the mutation will fail with an error.

Alternatively if your ID doesn't specify both class and id, resolvers have a load_#{argument} method that can be overridden.

argument :employee_id, ID, loads: Types::Employee

def load_employee(id)
  ::Employee.find(id)
end

If you don't want this behavior, don't use it. Instead, create arguments with type ID and use them your own way, for example:

# No special loading behavior:
argument :employee_id, ID

Can _this user_ perform _this action_? Copy Chapter

Sometimes you need to authorize a specific user-object(s)-action combination. For example, .admin? users can't promote all employees! They can only promote employees which they manage.

You can add this check by implementing a #authorized? method, for example:

def authorized?(employee:)
  super && context[:current_user].manager_of?(employee)
end

When #authorized? returns false (or something falsey), the mutation will be halted. If it returns true (or something truthy), the mutation will continue.

Adding errors

To add errors as data (as described in Mutation errors), return a value along with false, for example:

def authorized?(employee:)
  super && if context[:current_user].manager_of?(employee)
    true
  else
    return false, { errors: ["Can't promote an employee you don't manage"] }
  end
end

Alternatively, you can add top-level errors by raising GraphQL::ExecutionError, for example:

def authorized?(employee:)
  super && if context[:current_user].manager_of?(employee)
    true
  else
    raise GraphQL::ExecutionError, "You can only promote your _own_ employees"
  end
end

In either case (returning [false, data] or raising an error), the mutation will be halted.

Finally, doing the work Copy Chapter

Now that the user has been authorized in general, data has been loaded, and objects have been validated in particular, you can modify the database using #resolve:

def resolve(employee:)
  if employee.promote
    {
      employee: employee,
      errors: [],
    }
  else
    # See "Mutation Errors" for more:
    {
      errors: employee.errors.full_messages
    }
  end
end

Guides Mutations Mutation Classes (`guides/mutations/mutation_classes.md`) Copy Section

Mutation Classes

GraphQL mutations are special fields: instead of reading data or performing calculations, they may modify the application state. For example, mutation fields may:

• Create, update or destroy records in the database
• Establish associations between already-existing records in the database
• Increment counters
• Create, modify or delete files
• Clear caches

These actions are called side effects.

Like all GraphQL fields, mutation fields:

• Accept inputs, called arguments
• Return values via fields

GraphQL-Ruby includes two classes to help you write mutations:

• GraphQL::Schema::Mutation, a bare-bones base class
• GraphQL::Schema::RelayClassicMutation, a base class with a set of nice conventions that also supports the Relay Classic mutation specification.

Besides those, you can also use the plain field API to write mutation fields.

Example mutation class Copy Chapter

If you used the install generator, a base mutation class will already have been generated for you. If that's not the case, you should add a base class to your application, for example:

class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
  # Add your custom classes if you have them:
  # This is used for generating payload types
  object_class Types::BaseObject
  # This is used for return fields on the mutation's payload
  field_class Types::BaseField
  # This is used for generating the `input: { ... }` object type
  input_object_class Types::BaseInputObject
end

Then extend it for your mutations:

class Mutations::CreateComment < Mutations::BaseMutation
  null true
  argument :body, String
  argument :post_id, ID

  field :comment, Types::Comment
  field :errors, [String], null: false

  def resolve(body:, post_id:)
    post = Post.find(post_id)
    comment = post.comments.build(body: body, author: context[:current_user])
    if comment.save
      # Successful creation, return the created object with no errors
      {
        comment: comment,
        errors: [],
      }
    else
      # Failed save, return the errors to the client
      {
        comment: nil,
        errors: comment.errors.full_messages
      }
    end
  end
end

The #resolve method should return a hash whose symbols match the field names.

(See Mutation Errors for more information about returning errors.)

Also, you can configure null(false) in your mutation class to make the generated payload class non-null.

Hooking up mutations Copy Chapter

Mutations must be attached to the mutation root using the mutation: keyword, for example:

class Types::Mutation < Types::BaseObject
  field :create_comment, mutation: Mutations::CreateComment
end

Auto-loading arguments Copy Chapter

In most cases, a GraphQL mutation will act against a given global relay ID. Loading objects from these global relay IDs can require a lot of boilerplate code in the mutation's resolver.

An alternative approach is to use the loads: argument when defining the argument:

class Mutations::AddStar < Mutations::BaseMutation
  argument :post_id, ID, loads: Types::Post

  field :post, Types::Post

  def resolve(post:)
    post.star

    {
      post: post,
    }
  end
end

By specifying that the post_id argument loads a Types::Post object type, a Post object will be loaded via Schema.object_from_id with the provided post_id.

All arguments that end in _id and use the loads: method will have their _id suffix removed. For example, the mutation resolver above receives a post argument which contains the loaded object, instead of a post_id argument.

The loads: option also works with list of IDs, for example:

class Mutations::AddStars < Mutations::BaseMutation
  argument :post_ids, [ID], loads: Types::Post

  field :posts, [Types::Post]

  def resolve(posts:)
    posts.map(&:star)

    {
      posts: posts,
    }
  end
end

All arguments that end in _ids and use the loads: method will have their _ids suffix removed and an s appended to their name. For example, the mutation resolver above receives a posts argument which contains all the loaded objects, instead of a post_ids argument.

In some cases, you may want to control the resulting argument name. This can be done using the as: argument, for example:

class Mutations::AddStar < Mutations::BaseMutation
  argument :post_id, ID, loads: Types::Post, as: :something

  field :post, Types::Post

  def resolve(something:)
    something.star

    {
      post: something
    }
  end
end

In the above examples, loads: is provided a concrete type, but it also supports abstract types (i.e. interfaces and unions).

Resolving the type of loaded objects Copy Section

When loads: gets an object from Schema.object_from_id, it passes that object to Schema.resolve_type to confirm that it resolves to the same type originally configured with loads:.

Handling failed loads Copy Section

If loads: fails to find an object or if the loaded object isn't resolved to the specified loads: type (using Schema.resolve_type), a GraphQL::LoadApplicationObjectFailedError is raised and returned to the client.

You can customize this behavior by implementing def load_application_object_failed in your mutation class, for example:

def load_application_object_failed(error)
  raise GraphQL::ExecutionError, "Couldn't find an object for ID: `#{error.id}`"
end

Or, if load_application_object_failed returns a new object, that object will be used as the loads: result.

Handling unauthorized loaded objects Copy Section

When an object is loaded but fails its .authorized? check, a GraphQL::UnauthorizedError is raised. By default, it's passed to Schema.unauthorized_object (see Handling Unauthorized Objects). You can customize this behavior by implementing def unauthorized_object(err) in your mutation, for example:

def unauthorized_object(error)
  # Raise a nice user-facing error instead
  raise GraphQL::ExecutionError, "You don't have permission to modify the loaded #{error.type.graphql_name}."
end

Guides Mutations Mutation Errors (`guides/mutations/mutation_errors.md`) Copy Section

Mutation errors

How can you handle errors inside mutations? Let's explore a couple of options.

Raising Errors Copy Chapter

One way to handle an error is by raising, for example:

def resolve(id:, attributes:)
  # Will crash the query if the data is invalid:
  Post.find(id).update!(attributes.to_h)
  # ...
end

Or:

def resolve(id:, attributes:)
  if post.update(attributes)
    { post: post }
  else
    raise GraphQL::ExecutionError, post.errors.full_messages.join(", ")
  end
end

This kind of error handling does express error state (either via HTTP 500 or by the top-level "errors" key), but it doesn't take advantage of GraphQL's type system and can only express one error at a time. It works, but a stronger solution is to treat errors as data.

Errors as Data Copy Chapter

Another way to handle rich error information is to add error types to your schema, for example:

class Types::UserError < Types::BaseObject
  description "A user-readable error"

  field :message, String, null: false,
    description: "A description of the error"
  field :path, [String],
    description: "Which input value this error came from"
end

Then, add a field to your mutation which uses this error type:

class Mutations::UpdatePost < Mutations::BaseMutation
  # ...
  field :errors, [Types::UserError], null: false
end

And in the mutation's resolve method, be sure to return errors: in the hash:

def resolve(id:, attributes:)
  post = Post.find(id)
  if post.update(attributes)
    {
      post: post,
      errors: [],
    }
  else
    # Convert Rails model errors into GraphQL-ready error hashes
    user_errors = post.errors.map do |error|
      # This is the GraphQL argument which corresponds to the validation error:
      path = ["attributes", error.attribute.to_s.camelize(:lower)]
      {
        path: path,
        message: error.message,
      }
    end
    {
      post: post,
      errors: user_errors,
    }
  end
end

Now that the field returns errors in its payload, it supports errors as part of the incoming mutations, for example:

mutation($postId: ID!, $postAttributes: PostAttributes!) {
  updatePost(id: $postId, attributes: $postAttributes) {
    # This will be present in case of success or failure:
    post {
      title
      comments {
        body
      }
    }
    # In case of failure, there will be errors in this list:
    errors {
      path
      message
    }
  }
}

In case of a failure, you might get a response like:

{
  "data" => {
    "createPost" => {
      "post" => nil,
      "errors" => [
        { "message" => "Title can't be blank", "path" => ["attributes", "title"] },
        { "message" => "Body can't be blank", "path" => ["attributes", "body"] }
      ]
    }
  }
}

Then, client apps can show the error messages to end users, so they might correct the right fields in a form, for example.

Nullable Mutation Payload Fields Copy Chapter

To benefit from "Errors as Data" described above, mutation fields must not have null: false. Why?

Well, for non-null fields (which have null: false), if they return nil, then GraphQL aborts the query and removes those fields from the response altogether.

In mutations, when errors happen, the other fields may return nil. So, if those other fields have null: false, but they return nil, the GraphQL will panic and remove the whole mutation from the response, including the errors!

In order to have the rich error data, even when other fields are nil, those fields must have null: true (which is the default) so that the type system can be obeyed when errors happen.

Here's an example of a nullable field (good!):

class Mutations::UpdatePost < Mutations::BaseMutation
  # Use the default `null: true` to support rich errors:
  field :post, Types::Post
  # ...
end

Guides Mutations Mutation Root (`guides/mutations/mutation_root.md`) Copy Section

Mutation Root

GraphQL mutations all begin with the mutation keyword:

mutation($accountNumber: ID!, $newBalance: Int!) {
# ^^^^ here
  setAccountBalance(accountNumber: $accountNumber, newBalance: $newBalance) {
    # ...
  }
}

Operations that begin with mutation get special treatment by the GraphQL runtime: root fields are guaranteed
to be executed sequentially. This way, the effect of a series of mutations is predictable.

Mutations are executed by a specific GraphQL object, Mutation. This object is defined like any other GraphQL object:

class Types::Mutation < Types::BaseObject
  # ...
end

Then, it must be attached to your schema with the mutation(...) configuration:

class Schema < GraphQL::Schema
  # ...
  mutation(Types::Mutation)
end

Now, whenever an incoming request uses the mutation keyword, it will go to Mutation.

See Mutation Classes for some helpers to define mutation fields.

Guides Object Cache Caching (`guides/object_cache/caching.md`) Copy Section

Caching Results

GraphQL::Enterprise::ObjectCache supports several different caching configurations for objects and fields. To get started, include the extension in your base object class and base field class and use cacheable(...) to set up the default cache behavior:

# app/graphql/types/base_object.rb
class Types::BaseObject < GraphQL::Schema::Object
  include GraphQL::Enterprise::ObjectCache::ObjectIntegration
  field_class Types::BaseField
  cacheable(...) # see below
  # ...
end

# app/graphql/types/base_field.rb
class Types::BaseField < GraphQL::Schema::Field
  include GraphQL::Enterprise::ObjectCache::FieldIntegration
  cacheable(...) # see below
  # ...
end

Also, make sure your base interface module is using your field class:

# app/graphql/types/base_interface.md
module Types::BaseInterface
 field_class Types::BaseField
end

Field caching can be configured per-field, too, for example:

field :latest_update, Types::Update, null: false, cacheable: { ttl: 60 }

field :random_number, Int, null: false, cacheable: false

Only queries are cached. ObjectCache skips mutations and subscriptions altogether.

`cacheable(true|false)` Copy Chapter

cacheable(true) means that the configured type or field may be stored in the cache until its cache fingerprint changes. It also defaults to public: false, meaning that clients will not share cached responses. See public: below for more about this option.

cacheable(false) disables caching for the configured type or field. Any query that includes this type or field will neither check for an already-cached value nor update the cache with its result.

`public:` Copy Chapter

cacheable(public: false) means that a type or field may be cached, but Schema.private_context_fingerprint_for(ctx) should be included in its cache key. In practice, this means that each client can have its own cached responses. Any query that contains a cacheable(public: false) type or field will use a private cache key.

cacheable(public: true) means that cached values from this type or field may be shared by all clients. Use this for public-facing data which is the same for all viewers. Queries that include only public: true types and fields will not include Schema.private_context_fingerprint_for(ctx) in their cache keys. That way their responses will be shared by all clients who request them.

`ttl:` Copy Chapter

cacheable(ttl: seconds) expires any cached value after the given number of seconds, regardless of cache fingerprint. ttl: shines in a few cases:

• Objects that can't reliably generate a fingerprint value (for example, they have no .updated_at timestamp). In this case, a conservative ttl may be the only option for cache expiration.
• Or, root-level fields that should be expired after a certain amount of time. The root-level Query often has no backing object, so it won't have a cache fingerprint, either. Adding cacheable: { ttl: ... } to root level fields will provide some caching along with a guarantee about when they'll be expired.
• Or, list responses that may be difficult to invalidate properly (see below).

Under the hood, ttl: is implemented with Redis's EXPIRE.

Caching lists and connections Copy Chapter

Lists and connections require a little extra consideration. By default, each item in a list is registered with the cache, but when new items are created, they are unknown to the cache and therefore don't invalidate the cached result. There are two main approaches to address this.

`has_many` lists Copy Section

In order to effectively bust the cache, items that belong to the list of "parent" object should update the parent (eg, Rails .touch) whenever they're created, destroyed, or updated. For example, if there's a list of players on a team:

{
  team { players { totalCount } }
}

None of the specific Players will be part of the cached response, but the Team will be. To properly invalidate the cache, the Team's updated_at (or other cache key) should be updated whenever a Player is added or removed from the Team.

If a list may be sorted, then updates to Players should also update the Team so that any sorted results in the cache are invalidated, too. Alternatively (or additionally), you could use a ttl: to expire cached results after a certain duration, just to be sure that results are eventually expired.

With Rails, you can accomplish this with:

# update the team whenever a player is saved or destroyed:
  belongs_to :team, touch: true

Top-level lists Copy Section

For ActiveRecord::Relations without a "parent" object, you can use GraphQL::Enterprise::ObjectCache::CacheableRelation to make a synthetic cache entry for the whole relation. To use this class, make a subclass and implement def items, for example:

class AllTeams < GraphQL::Enterprise::ObjectCache::CacheableRelation
  def items(division: nil)
    teams = Team.all
    if division
      teams = teams.where(division: division)
    end
    teams
  end
end

Then, in your resolver, use your new class to retrieve the items:

class Query < GraphQL::Schema::Object
  field :teams, Team.connection_type do
    argument :division, Division, required: false
  end

  def teams(division: nil)
    AllTeams.items_for(self, division: division)
  end
end

If you're using GraphQL::Schema::Resolver, you'd call .items_for slightly differently:

def resolve(division: nil)
  # use `context[:current_object]` to get the GraphQL::Schema::Object instance whose field is being resolved
  AllTeams.items_for(context[:current_object], division: division)
end

Finally, you'll need to handle CacheableRelations in your object identification methods, for example:

class MySchema < GraphQL::Schema
  # ...
  def self.id_from_object(object, type, ctx)
    if object.is_a?(GraphQL::Enterprise::ObjectCache::CacheableRelation)
      object.id
    else
      # The rest of your id_from_object logic here...
    end
  end

  def self.object_from_id(id, ctx)
    if (cacheable_rel = GraphQL::Enterprise::ObjectCache::CacheableRelation.find?(id))
      cacheable_rel
    else
      # The rest of your object_from_id logic here...
    end
  end
end

In this example, AllTeams implements several methods to support caching:

• #id creates a cache-friendly, stable global ID
• #to_param creates a cache fingerprint (using Rails's #cache_key under the hood)
• .find? retrieves the list based on its ID

This way, if a Team is created, the cached result will be invalidated and a fresh result will be created.

Alternatively (or additionally), you could use a ttl: to expire cached results after a certain duration, just to be sure that results are eventually expired.

Connections Copy Section

By default, connection-related objects (like *Connection and *Edge types) "inherit" cacheability from their node types. You can override this in your base classes as long as GraphQL::Enterprise::ObjectCache::ObjectIntegration is included in the inheritance chain somewhere.

Caching Introspection Copy Chapter

By default, introspection fields are considered public for all queries. This means that they are considered cacheable and their results will be reused for any clients who request them. When adding the ObjectCache to your schema, you can provide some options to customize this behavior:

• cache_introspection: { public: false, ... } to use public: false for all introspection fields. Use this if you hide schema members for some clients.
• cache_introspection: false to completely disable caching on introspection fields.
• cache_introspection: { ttl: ..., ... } to set a ttl (in seconds) for introspection fields.

Object Dependencies Copy Chapter

By default, the object of a GraphQL Object type is used for caching the fields selected on that object. But, you can specify what object (or objects) should be used to check the cache by implementing def self.cache_dependencies_for(object, context) in your type definition. For example:

class Types::Player
  def self.cache_dependencies_for(player, context)
    # we update the team's timestamp whenever player details change,
    # so ignore the `player` for caching purposes
    player.team
  end
end

Use this to:

• improve performance when caching lists of children that belong to a parent object
• register other objects with the ObjectCache when running a query. (cacheable_object(obj) or def self.object_fingerprint_for can also be used in this case.)

If this method returns an Array, each object in the array will be registered with the cache.

Guides Object Cache Memcached (`guides/object_cache/memcached.md`) Copy Section

Dalli Configuration

GraphQL::Enterprise::ObjectCache can also run with a Memcached backend via the Dalli client gem.

Set it up by passing a Dalli::Client instance as dalli: ..., for example:

use GraphQL::Enterprise::OperationStore, dalli: Dalli::Client.new(...)

Guides Object Cache Redis (`guides/object_cache/redis.md`) Copy Section

Redis Configuration

GraphQL::Enterprise::ObjectCache requires a Redis connection to store cached responses. Unlike OperationStore or rate limiters, this Redis instance should be configured to evict keys as needed.

Memory Management Copy Chapter

Memory consumption is hard to estimate since it depends on how many queries the cache receives, how many objects those queries reference, how big the response is for those queries, and how long the fingerprints are for each object and query. To manage memory, configure the Redis instance with a maxmemory and maxmemory-policy directive, for example:

maxmemory 1gb
maxmemory-policy allkeys-lfu

Additionally, consider conditionally skipping the cache to prioritize your most critical GraphQL traffic.

Redis Cluster Copy Chapter

ObjectCache also supports Redis Cluster. To use, pass redis_cluster::

use GraphQL::Enterprise::ObjectCache, redis_cluster: Redis::Cluster.new(...)

Under the hood, it uses query fingerprints as hash tags and each cached result has its own set of object metadata.

Connection Pool Copy Chapter

ObjectCache also supports ConnectionPool. To use it, pass connection_pool::

use GraphQL::Enterprise::ObjectCache, connection_pool: ConnectionPool.new(...) { ... }

Data Structure Copy Chapter

Under the hood, ObjectCache stores a mapping of queries and objects. Additionally, there are back-references from objects to queries that reference them. In general, like this:

"query1:result" => '{"data":{...}}'
"query1:objects" => ["obj1:v1", "obj2:v2"]

"query2:result" => '{"data":{...}}'
"query2:objects" => ["obj2:v2", "obj3:v1"]

"obj1:v1" => { "fingerprint" => "...", "id" => "...", "type_name" => "..." }
"obj2:v2" => { "fingerprint" => "...", "id" => "...", "type_name" => "..." }
"obj3:v1" => { "fingerprint" => "...", "id" => "...", "type_name" => "..." }

"obj1:v1:queries" => ["query1"]
"obj2:v2:queries" => ["query1", "query2"]
"obj3:v1:queries" => ["query2"]

These mappings enable proper clean-up when queries or objects are expired from the cache. Additionally, whenever ObjectCache finds incomplete data in storage (for example, a necessary key was evicted), then it invalidates the whole query and re-runs it.

Guides Object Cache Runtime Considerations (`guides/object_cache/runtime_considerations.md`) Copy Section

Runtime Considerations

With caching configured, here are a few more things to keep in mind while queries are running.

Skipping the cache Copy Chapter

You can set skip_object_cache: true in your query context: { ... } to disable ObjectCache for a given query.

Manually adding an object to caching Copy Chapter

By default, ObjectCache gathers the objects "behind" each GraphQL object in the result, then uses their fingerprints as cache keys. To manually register another object with the cache while a query is running, call Schema::Object.cacheable_object(...), passing the object and context. For example:

field :team_member_count, Integer, null: true do
  argument :name, String, required: true
end

def team_member_count(name:)
  team = Team.find_by(name: name)
  if team
    # Register this object so that the cached result
    # will be invalidated when the team is updated:
    Types::Team.cacheable_object(team, context)
    team.members.count
  else
    nil
  end
end

(When the cache is disabled, cacheable_object(...) is a no-op.)

Measuring the cache Copy Chapter

While the cache is running, it logs some data in a Hash as context[:object_cache]. For example:

result = MySchema.execute(...)
pp result.context[:object_cache]
{
  key: "...",                 # the cache key used for this query
  write: true,                # if this query caused an update to the cache
  ttl: 15,                    # the smallest `ttl:` value encountered in this query (used for this query's result)
  hit: true,                  # if this query returned a cached result
  public: false,              # true or false, whether this query used a public cache key or a private one
  messages: ["...", "..."],   # status messages about the cache's behavior
  objects: Set(...),          # application objects encountered during the query
  uncacheable: true,          # if ObjectCache found a reason that this query couldn't be cached (see `messages: ...` for reason)
  reauthorized_cached_objects: true,
                              # if `.authorized?` was checked for cached objects, see "Disabling Reauthorization"
}

Manually refreshing the cache Copy Chapter

If you need to manually clear the cache for a query, pass context: { refresh_object_cache: true, ... }. This will cause the ObjectCache to remove the already-cached result (if there was one), reassess the query for cache validity, and return a freshly-executed result.

Usually, this shouldn't be necessary; making sure objects update their cache fingerprints will cause entries to expire when they should be re-executed. See also Schema fingerprint for expiring all results in the cache.

Guides Object Cache Schema Setup (`guides/object_cache/schema_setup.md`) Copy Section

Schema Setup

To prepare the schema to serve cached responses, you have to add GraphQL::Enterprise::ObjectCache and implement a few hooks.

Add the Cache Copy Chapter

In your schema, add use GraphQL::Enterprise::ObjectCache, redis: ...:

class MySchema < GraphQL::Schema
  use GraphQL::Enterprise::ObjectCache, redis: CACHE_REDIS
end

See the Redis guide or Memcached guide for details about configuring cache storage.

Additionally, it accepts some options for customizing how introspection is cached, see Caching Introspection

Context Fingerprint Copy Chapter

Additionally, you should implement def self.private_context_fingerprint_for(context) to return a string identifying the private scope of the given context. This method will be called whenever a query includes a public: false type or field. For example:

class MySchema < GraphQL::Schema
  # ...
  def self.private_context_fingerprint_for(context)
    viewer = context[:viewer]
    if viewer.nil?
      # This should never happen, but just in case:
      raise("Invariant: No viewer in context! Can't create a private context fingerprint" )
    end

    # include permissions in the fingerprint so that if the viewer's permissions change, the cache will be invalidated
    permission_fingerprint = viewer.team_memberships.map { |tm| "#{tm.team_id}/#{tm.permission}" }.join(":")

    "user:#{viewer.id}:#{permission_fingerprint}"
  end
end