2. Journey through the supergraph


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

In this lesson, we will:

  • Trace the journey of a client request through the
  • Describe how the creates query plans to resolve GraphQL s across multiple s

In the beginning...

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

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

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

Note: If you've completed GraphOS: Safe API delivery, the next section will feel familiar!

The launch process

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

When the gets a new schema, or an updated version of an existing subgraph schema, it starts to build the supergraph schema. The attempts to combine all of the schemas from its registered s into a single 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 , and then try publishing the subgraph again.

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

The automatically sends the schema to an internal service within called Apollo Uplink. Uplink is a server that stores the latest supergraph schema for each graph. The 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 s to the , this time within the context of having multiple s.

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 to the . The client has no clue which s belong to which s—or even that there are subgraphs at all!

Client sends a GraphQL operation to the router

Step 2: Building a query plan

The looks at the s in the and uses the supergraph schema to figure out which s are responsible for resolving each .

Router uses the supergraph schema

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

Router builds a query plan

Step 3: Executing the query plan

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

Router sends operations to subgraphs

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

Subgraphs resolve data

Step 4: The subgraph responses

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

Subgraphs return data

Step 5: Sending data back to the client

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

Subgraphs return data

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

The full journey of an operation through the supergraph, in one diagram

Key takeaways

  • The uses the to create a query plan for the incoming GraphQL . The query plan is a list of smaller operations the router can execute on different s to fully resolve the incoming operation.
  • The carries out the query plan by executing the list of s on the appropriate s.
  • The combines all the responses from the s 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 to our .


Share your questions and comments about this lesson

This course is currently in

. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.