3. Creating a supergraph
10m

Overview

Let's bring our into the world.

In this lesson, we will:

  • Use our listings to create a new
  • Set up our environment variables

From subgraph to supergraph

As we learned in the last lesson, we can make our single —listings—the very first piece in a . Growing from "sub" to "super" is actually a lot easier than it sounds.

Ready to go? Let's jump in.

Creating a new graph

Check your plan: Part of this course covers the self-hosted GraphOS Router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won't be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.

  1. Open a new browser window and go to GraphOS Studio.

  2. If you haven't created a in Studio before now, you'll be prompted to do so. Otherwise, we can create a new graph by clicking the + Create New Graph button in the upper right corner of the dashboard.

    studio.apollographql.com

    The New Graph button in Studio

  3. We'll give our a descriptive title, keep the default settings for Graph Architecture as "", then click Next.

    studio.apollographql.com

    The create graph modal in Studio, filled out with the name Airlock

    If you don't see the modal above, you may be on the wrong plan.

    Check your plan: Part of this course covers the self-hosted GraphOS Router, which requires a GraphOS Enterprise plan. You can still follow along if your organization is on a different plan, but you won't be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.

  4. We should now see a modal with options for publishing a schema.

    studio.apollographql.com

    A modal window showing options for publishing the schema for our graph

We're ready to publish our schema!

Task!

Publishing the listings schema

To publish our listings schema to our new , we'll use the . Rover lets us connect to our graph from the command line and publish schemas, but it needs a couple of pieces of data first.

  • APOLLO_KEY: Your 's API key, used to interact with a single in . It starts with something like "service:your-graph-name". Note that this is different from your personal API key, which we used to authenticate in the first lesson, and which grants you partial access to every in the organization you belong to.
  • APOLLO_GRAPH_REF: The erence (or graph ref) for our , which we'll use to tell where to publish our . A graph ref starts with the graph's ID, followed by an @ symbol, followed by the .

We'll use these values again when we run the , so we can store them in a new file we'll add to the router directory called .env.

Let's create that file now.

📦 dgs-federation
┣ 📂 router
┃ ┣ 📄 router-config.yaml
┃ ┗ 📄 .env
┗ 📂 listings
Task!

Storing variables

  1. Go back to the configuration options in Studio that appeared after you created your . Make sure you're on the Schema Document tab.

  2. First, make sure that the Supergraph Pipeline Track dropdown is set to Federation 2.7 Supergraph. This specifies that our should be built using the latest features of .

    studio.apollographql.com

    The schema publish modal, highlighting the Supergraph Pipeline Track dropdown

  3. Below, take a little peek at the command for publishing a . We'll be running this command shortly, but for now, we're more interested in the APOLLO_KEY environment variable here.

    APOLLO_KEY=your-graphs-apollo-key \
    rover subgraph publish your-graph-name@current \
    --name products --schema ./products-schema.graphql \
    --routing-url http://products.prod.svc.cluster.local:4001/graphql
  4. Click on the eye icon on the code block to reveal the full value of APOLLO_KEY. Copy APOLLO_KEY and its value into the router/.env file. We'll need it for the next step, and won't have access to the same key again through Studio.

    studio.apollographql.com

    The Apollo Key value outlined, along with the eye icon that toggles the value from hidden to visible

    router/.env
    APOLLO_KEY=your-unique-apollo-api-key
  5. Now let's go back to Studio to get our . The value we're looking for appears in the same code block, directly after the " publish" part of the command. We'll save this value as an environment variable as well, but we can access it anytime from our graph's home page.

    studio.apollographql.com

    The graph ref value outlined

    APOLLO_KEY=your-graphs-apollo-key \
    rover subgraph publish your-graph-name@current \
    --name products --schema ./products-schema.graphql \
    --routing-url http://products.prod.svc.cluster.local:4001/graphql

Great! Before proceeding, we should make sure that we've saved both of our environment variables. We're about to put them to work!

router/.env
APOLLO_KEY=your-unique-apollo-api-key
APOLLO_GRAPH_REF=your-graph-name@current

We've got the values we need to publish our !

The rover subgraph publish command

has a command ready to help us with this important task: rover subgraph publish. This command pushes the latest version of a single to .

rover subgraph publish <APOLLO_GRAPH_REF> \
--name <SUBGRAPH NAME> \
--schema <SCHEMA FILE PATH> \
--routing-url <ROUTING URL>

To use this command, we need the for the we want to publish to and the following command line options:

OptionWhat is it?
--nameWhat we want to call our subgraph in GraphOS
--schemaThe relative path to our subgraph's schema file
--routing-urlThe URL where our subgraph runs (locally, for now)

Let's fill out this command for our listings .

Note: If your listings server is not already running, boot it up now!

  1. Bounce back to the terminal and make sure we're in the listings directory of our project.

  2. Now let's type out the rover subgraph publish command:

    We'll paste in the value of our APOLLO_GRAPH_REF environment variable.

    For the name option, we'll pass in listings.

    For the schema option, we'll pass the relative path to our schema.graphqls file. From the root of listings, that path is ./src/main/resources/schema/schema.graphqls.

    And for the routing-url option, we'll pass in localhost:8080/graphql (or wherever your listings service is running!).

    listings
    rover subgraph publish <APOLLO_GRAPH_REF> \
    --name listings \
    --schema ./src/main/resources/schema/schema.graphqls \
    --routing-url http://localhost:8080/graphql

    Note: We've used the \ character in this command to improve legibility by putting each command-line option on its own line. If you choose to type the entire rover subgraph publish command on a single line, you don't need to include the \.

  3. You'll see the following message: The host localhost is not routable via the public internet. Continuing the publish will make this subgraph reachable in local environments only. Would you still like to publish? [y/N] Go ahead and tap the y key. We'll stick to local environments for this course!

  4. If all is well in the world, running this command should output a message confirming that the has been published and the has been updated!

Reviewing results in Studio

Let's go back to Studio. We can click "See schema changes" in the modal to see what's changed in our .

studio.apollographql.com

The schema publish modal, now with the 'See schema changes' button highlighted

This takes us to a new page called Launches. A is the process that runs every time we make a change to our . We'll take a closer look at launches in an upcoming lesson.

studio.apollographql.com

The Launches page in Studio, showing that changes were made to our graph

For now let's click on the Schema tab in the sidebar. The Schema Reference page lets us see all the types and in our composed . That's right—even though we've only published one so far, we already have a supergraph schema!

We see that our 's Query type includes the two from the listings : featuredListings and listing. Each is annotated with its description, any it requires, and which it belongs to.

studio.apollographql.com

The Schema reference page in Studio, showing the Query type with two fields: featuredListings and listing

Let's take a closer look at that . Click on the SDL tab at the top of the Schema page. Here we can see details about our published , along with two additional schemas.

studio.apollographql.com

The Schema page opened up to the SDL tab, highlighted the two options: API schema and supergraph schema

The API schema is the API that gets exposed to your clients. It cleanly and logically represents the combination of your . (We won't worry about this schema for now.)

The Supergraph schema is used by the like a map, to define how incoming can be divided up among the underlying . We only have one at the moment, so all in an operation will be routed over to the listings .

Practice

What does the rover subgraph publish command do?

Key takeaways

  • We can use the rover subgraph publish command from the to publish our to .
  • The consolidates all the types and across our published . It also includes extra to help the determine which subgraphs can resolve each field.

Up next

Our is set up, and we're just missing one piece: the ! Next up, let's get the router running, send it some queries, and inspect the insights from !

Previous

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.