Overview

What actually happens when we add a new subgraph to Poetic Plates?

In this lesson, we will:

• Trace the journey of a client request through the supergraph
• Describe how the router creates query plans to resolve GraphQL operations across multiple subgraphs

In the beginning...

We started off from humble cooking beginnings: a small subgraph called recipes. Clients sent queries to the router, which routed the queries to the recipes subgraph. Simple! Because we only had one subgraph, that subgraph's schema and the supergraph schema were essentially one and the same.

Now that we want to add another subgraph to the mix, what happens?

First, we'll need to publish that subgraph schema to GraphOS. This will trigger a launch.

The launch process

A launch represents the complete process of making schema updates to a graph.

When the schema registry gets a new subgraph schema, or an updated version of an existing subgraph schema, it starts to build the supergraph schema. The schema registry attempts to combine all of the schemas from its registered subgraphs into a single supergraph schema. This process is also known as composition.

If composition fails, we'll see an error in Studio, and the process stops there. No stress: we can use the error messages to fix the issue in our subgraph, and then try publishing the subgraph again.

If composition succeeds and there are no validation errors, the schema registry produces a supergraph schema. (In the next section, we'll find out how the router uses this supergraph schema.)

The schema registry automatically sends the supergraph schema to an internal service within GraphOS called Apollo Uplink. Uplink is a server that stores the latest supergraph schema for each graph. The router fetches the latest schema from Uplink and uses this new schema to respond to client requests.

With that, the launch completes successfully!

Exciting stuff! Now, let's revisit the experience of sending operations to the supergraph, this time within the context of having multiple subgraphs.

The journey of a GraphQL operation through the supergraph

Let's start at the beginning: from the client request.

Step 1: The client request

First, the client sends a GraphQL operation to the router. The client has no clue which fields belong to which subgraphs—or even that there are subgraphs at all!

Step 2: Building a query plan

The router looks at the fields in the operation and uses the supergraph schema to figure out which subgraphs are responsible for resolving each field.

It uses this information to build a query plan, a list of smaller GraphQL operations to execute on the subgraphs. The query plan also specifies the order in which the subgraph operations need to run.

Step 3: Executing the query plan

Next, the router carries out the query plan by sending the smaller GraphQL operations to each of the subgraphs it needs data from.

The subgraphs resolve the operations the same way as any other GraphQL server: they use their resolvers and data sources to retrieve and populate the requested data.

Step 4: The subgraph responses

The subgraphs send back the requested data to the router, and then the router combines all those responses into a single JSON object.

Step 5: Sending data back to the client

Finally, the router sends the JSON object back to the client.

And that's the end of our operation's journey!

Key takeaways

• The router uses the supergraph schema to create a query plan for the incoming GraphQL operation. The query plan is a list of smaller operations the router can execute on different subgraphs to fully resolve the incoming operation.
• The router carries out the query plan by executing the list of operations on the appropriate subgraphs.
• The router combines all the responses from the subgraphs into a single JSON object, which it sends back to the client.

Up next

Let's see this process in action! In the next lesson, we'll add the kitchenware subgraph to our supergraph.