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.
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
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.
Suppose we want the parent schema to delegate retrieval of repositories to the subschema, in order to execute queries such as this one:
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:
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
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.
delegateToSchema method should be called with the following named options:
A subschema to delegate to.
operation: 'query' | 'mutation' | 'subscription'
The operation type to use during the delegation.
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:
If we delegate at
Query.bookingsByUser, we want to preserve the
limit argument and add a
userId argument by using the
User.id. So the resolver would look like the following:
context: Record<string, any>
GraphQL context that is going to be passed to the subschema execution or subsciption call.
GraphQL resolve info of the current resolver. Provides access to the subquery that starts at the current resolver.
transforms: Array < 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