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.

API

delegateToSchema

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 User.id. So the resolver would look like the following:

const resolvers = {
User: {
bookings(parent, args, context, info) {
return delegateToSchema({
schema: subschema,
operation: 'query',
fieldName: 'bookingsByUser',
args: {
userId: parent.id,
},
context,
info,
});
},
...
},
...
};

context: Record<string, any>

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

info: GraphQLResolveInfo

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 transformRequest and transformResult functions.