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 chirps and authors service example:
We may want to navigate from a particular user to their chirps, or from a chirp to its author. This is possible within our service architecture by connecting an existing key of each object to a corresponding root query:
Chirp.authorId -> userById(id)gets a Chirp's author.
User.id -> chirpsByAuthorId(authorId)gets a User's chirps.
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 extentions (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:
Chirp.author, 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,
Chirp.author will require that a Chirp provide its
authorId. 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 guarentee that these fields are fetched. Dynamic selection sets are also possible by providing a function that recieves a GraphQL
FieldNode (the gateway field) and returns a
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
Chirp.author from an array of ten chirps—that would delegate ten individual
userById queries while resolving each author! 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 authors service that allows fetching many users at once:
With this many-users query available, we can now delegate the
Chirp.author 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.
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.
Passing gateway arguments
Exhaustive accessors like
User.chirps do not scale well (...what happens when a user has tens of thousands of chirps?), 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.chirps 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 Chirps service defines this association. The first thing we'll need is a corresponding argument in the chirps query; and while we're at it, let's also support batching:
chirpPagesByAuthorIds query is a very primitive example of pagination, and simply returns an array of chirps for each author 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 chirps have a many-to-many relationship and the users service owns the association data. That might give us a
User.chirpIds 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:
Extending transformed schemas
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
chirpsByAuthorIdthat have been removed from the gateway schema.