Schema extensions add gateway-level type definitions and resolvers into a combined API, which is useful for establishing connections between types that exist in separate subschemas.
When considering these capabilities, be sure to compare them with the newer automated features available through type merging. While type merging frequently eliminates the need for schema extensions, it does not preclude their use.
Going back to the posts and users service example:
We may want to navigate from a particular user to their posts, or from a post to its user. This is possible within our service architecture by connecting an existing key of each object to a corresponding root query:
Post.userId -> userById(id)gets a Post's user.
User.id -> postsByUserId(userId)gets a User's posts.
To formalize this navigation within our gateway schema, we can extend each type with a new field that will translate its respective key into an actual object association:
typeDefs option provides type extensions (using the
extend keyword) that add additional fields into the combined gateway schema, and therefore may cross-reference types from any subschema.
However, these extensions alone won't do anything until they have corresponding resolvers. A complete example would look like this:
Post.user, we delegate each key reference to its corresponding root query. Note that the structure of stitching resolvers has a
selectionSet property and a
selectionSet specifies the key field(s) needed from an object to query for its associations. For example,
Post.user will require that a Post provide its
userId. Rather than relying on incoming queries to manually request this key for the association, the selection set will automatically be included in subschema requests to guarantee that these fields are fetched. Dynamic selection sets are also possible by providing a function that receives a GraphQL
FieldNode (the gateway field) and returns a
Note: As of version 7 of graphql-tools,
fragment hints are removed in favor of
selectionSet hints, read more in migration guide.
Resolvers use the
delegateToSchema function to forward parts of queries (or even whole new queries) to any other schema—inside or outside of the stitched schema. When delegating to a stitched subschema, always provide the complete subschema config object as the
delegateToSchema assumes that the delegated operation will return the same GraphQL type as the resolved field (ex: a
User field would delegate to a
User query). If this is not the case, then you should manually provide a
returnType option citing the expected GraphQL return type, and transform the result accordingly in the resolver.
The drawback of performing individual
delegateToSchema calls is that they can be fairly inefficient. Say we request
Post.user from an array of ten posts—that would delegate ten individual
userById queries while resolving each user! To improve this, we can instead delegate in batches, where many instances of a field resolver are consolidated into one delegation.
To setup batching, the first thing we'll need is a new query in the users service that allows fetching many users at once:
With this many-users query available, we can now delegate the
Post.user field in batches across many records:
batchDelegateToSchema wraps a single
delegateToSchema call in a DataLoader scoped by context, field, arguments, and query selection. It assumes that the delegated operation will return an array of objects matching the gateway field's named GraphQL type (ex: a
User field delegates to a
[User] query). If this is not the case, then you should manually provide a
returnType option citing the expected GraphQL return type. Since it is a thin wrapper around
DataLoader, it also makes the following assumptions on the results:
- The Array of values must be the same length as the Array of keys.
- Each index in the Array of values must correspond to the same index in the Array of keys.
If the query you're delegating to doesn't conform to these expectations, you can provide a custom valuesFromResults function to transform it appropriately.
Batch delegation is generally preferable over plain delegation because it eliminates the redundancy of requesting the same field across an array of parent objects. Even so, delegation costs can add up because there is still one subschema request made per batched field—for remote services, this may create many network requests sent to the same service. Consider enabling an additional layer of network-level batching with a package such as apollo-link-batch-http to consolidate requests per subschema.
Exhaustive accessors like
User.posts do not scale well (...what happens when a user has tens of thousands of posts?), so the gateway should probably accept scoping arguments and pass them through to the underlying subschemas. Let's add a
pageNumber argument to the
User.posts schema extension:
This argument only exists in the gateway schema and won't do anything until passed through to subschemas. How we pass this input through depends on which subservice owns the association data...
First, let's say that the Posts service defines this association. The first thing we'll need is a corresponding argument in the posts query; and while we're at it, let's also support batching:
postPagesByUserIds query is a very primitive example of pagination, and simply returns an array of posts for each user ID. Now we just need to pass the resolver's page number argument through to
batchDelegateToSchema, and manually specify a
returnType that matches the pagination format:
Alternatively, let's say that users and posts have a many-to-many relationship and the users service owns the association data. That might give us a
User.postIds field to stitch from:
In this configuration, resolver arguments will need to pass through with the initial
forwardArgsToSelectionSet helper handles this:
forwardArgsToSelectionSet will pass through all arguments from the gateway field to all root fields in the selection set. For complex selections that request multiple fields, you may provide an additional mapping of selection names with their respective arguments:
Transformed schemas are nuanced because they involve two versions of the same schema: the original schema, and the transformed gateway schema. When extending a transformed schema, we extend the gateway schema but delegate to the original schema. For example:
A few key points to note here:
All schema extensions and their resolvers exist in the gateway schema, and therefore refer to the transformed type name
Delegations refer to the original subschema, and therefore may reference fields such as
postsByUserIdthat have been removed from the gateway schema.