The Guild LogoThe Guild Monogram
GraphQL Tools

GraphQL Tools

A set of utilities for faster GraphQL development

Get Started

Schema delegation#

Schema delegation is a way to automatically forward a query (or a part of a query) from a parent schema to another schema (called a subschema) that is able to execute the query. Delegation is useful when the parent schema shares a significant part of its data model with the subschema. For example:

  • A GraphQL gateway that connects multiple existing endpoints together, each with its own schema, could be implemented as a parent schema that delegates portions of queries to the relevant subschemas.
  • Any local schema can directly wrap remote schemas and optionally extend them with additional fields. As long as schema delegation is unidirectional, no gateway is necessary. Simple examples are schemas that wrap other autogenerated schemas (e.g. Postgraphile, Hasura, Prisma) to add custom functionality.

Delegation is performed by one function, delegateToSchema, called from within a resolver function of the parent schema. The delegateToSchema function sends the query subtree received by the parent resolver to the subschema that knows how to execute it. Fields for the merged types use the defaultMergedResolver resolver to extract the correct data from the query response.

The graphql-tools package provides several related tools for managing schema delegation:

  • Remote schemas - turning a remote GraphQL endpoint into a local schema
  • Schema wrapping - modifying existing schemas -- usually remote, but possibly local -- when wrapping them to make delegation easier
  • Schema stitching - merging multiple schemas into one

Motivational example#

Let's consider two schemas, a subschema and a parent schema that reuses parts of a subschema. While the parent schema reuses the definitions of the subschema, we want to keep the implementations separate, so that the subschema can be tested independently, or even used as a remote service.

# Subschema type Repository { id: ID! url: String issues: [Issue] userId: ID! } type Issue { id: ID! text: String! repository: Repository! } type Query { repositoryById(id: ID!): Repository repositoriesByUserId(id: ID!): [Repository] } # Parent schema type Repository { id: ID! url: String issues: [Issue] userId: ID! user: User } type Issue { id: ID! text: String! repository: Repository! } type User { id: ID! username: String repositories: [Repository] } type Query { userById(id: ID!): User }

Suppose we want the parent schema to delegate retrieval of repositories to the subschema, in order to execute queries such as this one:

query { userById(id: "1") { id username repositories { id url user { username id } issues { text } } } }

The resolver function for the repositories field of the User type would be responsible for the delegation, in this case. While it's possible to call a remote GraphQL endpoint or resolve the data manually, this would require us to transform the query manually, or always fetch all possible fields, which could lead to overfetching. Delegation automatically extracts the appropriate query to send to the subschema:

# To the subschema query ($id: ID!) { repositoriesByUserId(id: $id) { id url issues { text } } }

Delegation also removes the fields that don't exist on the subschema, such as user. This field would be retrieved from the parent schema using normal GraphQL resolvers.

Each field on the Repository and Issue types should use the defaultMergedResolver to properly extract data from the delegated response. Although in the simplest case, the default resolver can be used for the merged types, defaultMergedResolver resolves aliases, converts custom scalars and enums to their internal representations, and maps errors.



The delegateToSchema method should be called with the following named options:

delegateToSchema(options: { schema: GraphQLSchema; operation: 'query' | 'mutation' | 'subscription'; fieldName: string; args?: Record<string, any>; context: Record<string, any>; info: GraphQLResolveInfo; transforms?: Array<Transform>; }): Promise<any>

schema: GraphQLSchema#

A subschema to delegate to.

operation: 'query' | 'mutation' | 'subscription'#

The operation type to use during the delegation.

fieldName: string#

A root field in a subschema from which the query should start.

args: Record<string, any>#

Additional arguments to be passed to the field. Arguments passed to the field that is being resolved will be preserved if the subschema expects them, so you don't have to pass existing arguments explicitly, though you could use the additional arguments to override the existing ones. For example:

# Subschema type Booking { id: ID! } type Query { bookingsByUser(userId: ID!, limit: Int): [Booking] } # Schema type User { id: ID! bookings(limit: Int): [Booking] } type Booking { id: ID! }

If we delegate at User.bookings to Query.bookingsByUser, we want to preserve the limit argument and add a userId argument by using the So the resolver would look like the following:

import { delegateToSchema } from '@graphql-tools/delegate'; const resolvers = { User: { bookings(parent, args, context, info) { return delegateToSchema({ schema: subschema, operation: 'query', fieldName: 'bookingsByUser', args: { userId:, }, context, info, }); }, ... }, ... };

context: Record<string, any>#

GraphQL context that is going to be passed to the subschema execution or subscription call.

info: GraphQLResolveInfo#

GraphQL resolve info of the current resolver. Provides access to the subquery that starts at the current resolver.

transforms: Transform[]#

Any additional operation transforms to apply to the query and results. Transforms are specified similarly to the transforms used in conjunction with schema wrapping, but only the operational components of transforms will be used by delegateToSchema, i.e. any specified transformRequest and transformResult functions. The following transforms are automatically applied during schema delegation to translate between source and target types and fields:

  • ExpandAbstractTypes: If an abstract type within a document does not exist within the target schema, expand the type to each and any of its implementations that do exist.
  • FilterToSchema: Remove all fields, variables and fragments for types that don't exist within the target schema.
  • AddTypenameToAbstract: Add __typename to all abstract types in the document, necessary for type resolution of interfaces within the source schema to work.
  • CheckResultAndHandleErrors: Given a result from a subschema, propagate errors so that they match the correct subfield. Also provide the correct key if aliases are used.
  • AddSelectionSets: activated by schema stitching to add selection sets into outgoing requests from the gateway schema. These selections collect key fields used to perform queries for related records from other subservices.