3. Adding a subgraph
5m

Overview

Excited to add more to the Poetic Plates ? With , it's straightforward– we're only a couple clicks away!

In this lesson, we will:

  • Add a new subgraph to our supergraph using Studio
  • Learn about the launch process and how to inspect a launch in Studio
  • Inspect an operation's query plan

Introduction kitchenware 🍳

Welcome to the Kitchenware API, the ultimate guide to all things kitchenware! This API is a one-stop-shop for everything you need to know about pots, pans, and kitchen tools. We've got it all, from non-stick frying pans to cast iron skillets, and everything in between. The quality of your kitchenware can make or break a dish, so it includes detailed information on the materials used in each product, from stainless steel to ceramic to cast iron.

And once you've found the perfect kitchenware for your needs, we've got tips on how to keep it looking and performing its best. This API provides cleaning and care instructions for each type of kitchenware, so you can keep your pots and pans in top condition for years to come.

It's the perfect API to add to the Poetic Plates , which so far only has information about recipes!

The Kitchenware API is hosted on https://poetic-plates-kitchenware-api.herokuapp.com/. You can explore the using Sandbox by connecting to the endpoint.

You don't need to clone the repository, but feel free to browse the codebase if you're curious.

Let's welcome this subgraph into the Poetic Plates !

Adding a subgraph

  1. Head over to your 's page in Studio and navigate to the Subgraphs page. We can see that our recipes subgraph is already here, pointing to where we hosted it.

  2. Click Add a subgraph.

    Note: You can also add a subgraph using the Rover CLI. Click the arrow next to Add subgraph and select Add subgraph using the Rover CLI to find the instructions.

    https://studio.apollographql.com/

    Subgraphs page in Studio

  3. We'll need to provide two things about the subgraph: its URL and its name.

    https://studio.apollographql.com/

    Add a subgraph modal

    Routing URL
    https://poetic-plates-kitchenware-api.herokuapp.com/
    Subgraph name
    kitchenware
  4. Then, click Add subgraph. It takes a few moments for to check that the subgraph successfully composes with all other existing subgraphs and produces a . And that's it!

    https://studio.apollographql.com/

    Successfully added a subgraph

Inspecting the launch

We added a new subgraph, so let's head over to the Launches page in Studio to see if the launch completed successfully.

Select the most recent launch to view the progress and status. Looks like everything is all green checkmarks!

https://studio.apollographql.com/

Launches page in Studio

We can see that the subgraph was successfully added. The Build Inputs shows us the subgraphs used to create the new . This is what the redeployed cloud is now using!

https://studio.apollographql.com/

Build inputs for a launch

Our new supergraph schema

Let's check out the Changelog through the navigation menu to see what new features and capabilities the kitchenware subgraph has added to Poetic Plates.

https://studio.apollographql.com/

Changelog page in Studio

We can see a total of 14 additions all about kitchenware! Cookware, utensils, appliances... and two new entry points added to the Query type.

All of these new types and s are presumably all coming from the kitchenware subgraph. We can confirm which s are coming from which subgraph by heading over to the Schema page.

Under the Reference tab, with Query selected, we can see the entry points to our . The Subgraph column indicates the subgraph each is coming from!

https://studio.apollographql.com/

Schema reference page for the Query type in Studio

We've got two new s available from our Query entry point: allCookware and a specific cookware.

When we dig deeper into the Objects available in the , there also seem to be other types available in the kitchenware subgraph, such as Utensil and Appliance, though both are not currently accessible from the Query entry point. We'll be focusing on the Cookware type in this course.

https://studio.apollographql.com/

Schema reference page for Objects in Studio

Note: Curious about that green "E" label? It stands for "entity"! You can hover over it for more information, but we'll get to it in a later lesson, so stay tuned.

Our has officially grown!

Sending a query

With both recipes and kitchenware data under our fingertips, are you itching to put the power of our to the test? Let's try sending a query that involves both subgraphs.

Let's jump back to the Query tab in the Schema page, where we could see all our available entry points to the . Under the Actions column of the Schema page, click the Play icon right next to the cookware .

https://studio.apollographql.com/

Schema reference page in Studio, click the play icon next to the cookware field

This will open up with the Documentation tab showing the and what we can use to build our query.

https://studio.apollographql.com/

Explorer, with the cookware field open in the Documentation field

If you have an currently in the Operation panel, clear it or open up a new tab. We want to start fresh here!

From the Documentation panel, let's build a query for a specific cookware. If we click into the cookware , we can see from the type description that Cookware refers to "food preparation equipment, such as pots and pans".

We'll add all three s we have available - the name, description and cleaningInstructions. It also needs a name , so we'll add that too.

Under the Variables panel, we'll set the name to "cast iron skillet". That seems like a tricky piece of cookware to take care of, so the cleaning instructions should provide some nuggets of knowledge for us!

That's data from the kitchenware subgraph! Let's spice things up with data from the recipes subgraph too! Why don't we check out the names of some recently added recipes?

There's a handy shortcut in to search our for that . Hit Command + K or Ctrl + K to access the spotlight search. Start typing recently and the Query.recentlyAddedRecipes should pop up.

https://studio.apollographql.com/

Explorer using Spotlight to search for a specific field

We'll select that and now we can access it directly in the Documentation panel. Saves us a couple clicks, and it'll be especially helpful as our continues to grow!

Let's add the recentlyAddedRecipes and ask for the name as the sub.

Lastly, we'll rename the to be more explicit. Give it a name GetSkilletAndRecipes.

Your query should now look like this:

query GetSkilletAndRecipes($name: String) {
cookware(name: $name) {
name
description
cleaningInstructions
}
recentlyAddedRecipes {
name
}
}

And under the Variables section:

{
"name": "cast iron skillet"
}

Let's run it!

Woohoo, and we get data back! One query, but with data coming from two separate subgraphs 🤯🎉

Adding a subgraph was pretty straightforward! But right now, you might be feeling that the data in both subgraphs feel separate and siloed. There's nothing directly connecting cookware to recipes or vice versa. Wouldn't it be great to know what cookware a particular recipe uses and how to clean it, all in one clean query?

The new feature: a recipe's cookware

Here's an example of a dream query that lets us ask for details about a specific recipe: its description, instructions, and ingredients, plus the type of cookware it needs, a description of what it looks like, and how to clean it! We're armed with useful information to become a cooking expert!

query GetRecipeAndCookwareInformation {
recipe(id: "rec3j49yFpY2uRNM1") {
name
description
ingredients {
text
}
instructions
cookware {
name
description
cleaningInstructions
}
}
}

Note: We're including the recipe's id inline with the query here for ease of reference as we go through the course. In reality, this id would be extracted out into a .

Digging into the data the recipes subgraph has, each recipe already contains a list of cookware names involved in the recipe. The RecipesAPI datasource also includes a method to retrieve that list called getRecipeCookware.

What the recipes subgraph doesn't have are the s for its cookware's description and cleaning instructions--these are s that are available in the kitchenware subgraph!

So we'll need a way to connect the data between both subgraphs to make our dream query work (hint: it's called entities!).

But first, let's set up our local development environment to ensure that the changes we make to the recipes subgraph not only work correctly but also play nicely with the kitchenware subgraph!

Practice

To add a new subgraph, which of these values does GraphOS need to know?

Key takeaways

  • To add a new subgraph, we can use the Studio UI or Rover CLI.
  • We can view the router's query plan using Explorer.
  • A launch represents the complete process of making schema updates to a graph. A launch is triggered when a schema is published to GraphOS. We can inspect the results of a launch through the Studio Launches page.

Up next

Let's set ourselves up for local development in the next lesson.

Previous
Next

Share your questions and comments about this lesson

This course is currently in

beta
. 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.