Docs
Launch GraphOS Studio

Supergraph-specific Studio features


provides tools to help multiple teams collaborate on a and its .

Supergraph variants

Each variant of a Studio has its own , , change history, and metrics.

Different of a can even have completely different sets of :

Production
Router
Users
Products
Staging
Router
Users
Products
Reviews

This helps you test out adding new (or removing existing ones) in non-production environments.

When you publish a subgraph's schema, you can specify which of the you're publishing that schema to.

Adding a variant

You can add a new to your existing in the following ways:

Adding a variant in GraphOS Studio

NOTE

This method of adding a is available only to cloud . For other graph types, see Adding a variant via the Rover CLI

  1. Go to your 's Settings page in Studio and navigate to This Graph > Variants:

    Variant settings page in Studio
  2. Click Add a variant. The following dialog appears:

    Step 1 for adding a variant in Studio
  3. Provide a Variant Name and click Continue. The next step in the dialog appears:

    Step 2 for adding a variant in Studio
  4. Provide your first 's Routing URL (this is the URL that your new 's will use to communicate with the ), along with a Subgraph Name.

    • Creating a new always requires also creating the first for that variant.
  5. If Studio can't fetch your 's schema automatically from the routing URL, click Advanced options to provide the schema another way (such as by pasting the schema directly or introspecting a locally running server).

  6. Click Add a new variant. When the action completes, your new is listed on your organization's homepage in Studio.

Adding a variant via the Rover CLI

To add a new to your with , you publish its first 's schema! To do this, you use the exact same Rover command as updating an existing subgraph. The only difference is that you provide the name of the new to the command.

Learn about publishing subgraph schemas.

Managing subgraphs

After you create a cloud supergraph (or a new of one), you can view a list of its associated from the variant's Subgraphs page:

List of subgraphs for a cloud supergraph in Studio

The list includes each 's name and routing URL, along with type and counts for each subgraph's schema.

Adding a new subgraph

You can add your new to your in the following ways:

Adding a subgraph in GraphOS Studio

NOTE

This method of adding a is available only to cloud . For other graph types, see Adding a subgraph via the Rover CLI

  1. Go to your 's page in Studio:

    Variant subgraphs page in Studio
  2. Click Add a subgraph. The following dialog appears:

    Dialog for adding a subgraph in Studio
  3. Provide your 's Routing URL (this is the URL that your 's will use to communicate with the ), along with a Subgraph Name.

  4. If Studio can't fetch your 's schema automatically from the routing URL, click Advanced options to provide the schema another way (such as by pasting the schema directly or introspecting a locally running server).

  5. Click Add Subgraph. When the action completes, your new is listed on the Subgraphs page.

Adding a subgraph via the Rover CLI

To add a to your with , you publish the subgraph's schema! To do this, you use the exact same Rover command as updating an existing subgraph. The only difference is that you provide the name of the new to the command.

Learn about publishing subgraph schemas.

Modifying a subgraph

From your 's page, you can modify an existing subgraph's routing URL:

  1. Open the "◦◦◦" menu for the you want to modify:

    Menu for additional subgraph options in Studio
  2. Click Edit routing URL.

  3. In the dialog that appears, provide a new URL and click Update.

    • Your automatically begins using the new URL to communicate with your .

If you need to make any other modifications to an existing , use the . Learn about rover subgraph commands.

Deleting a subgraph

⚠️ CAUTION

Deleting a subgraph is dangerous! Read this section fully before deleting a .

You can delete an existing from a of your cloud . If you do:

  1. The automatically attempts to compose an updated using the schemas from all remaining .

    • Studio displays the result of this attempt, and you can cancel the deletion if there are errors.
  2. If composition succeeds, the 's automatically begins using the updated . This means clients can no longer the router for that are defined only in the deleted .

    If composition fails, the continues using its existing . This means clients can continue the router for from the deleted , until the remaining are updated to compose successfully.

⚠️ Important considerations

  • Deleting a subgraph can break existing clients! This action is equivalent to removing all the 's types and from your (unless they're also defined in another subgraph). If a client sends an that includes any of those types and fields, the will reject that operation.

    • To help you remove schema definitions safely, learn about schema checks.
  • Deleting a in Studio has no effect on your actual running subgraph instance. It only removes your 's knowledge of that instance and its corresponding schema .

Steps to delete within Studio

  1. Go to the page for the subgraph's corresponding .

  2. Open the "◦◦◦" menu for the you want to delete:

    Menu for additional subgraph options in Studio
  3. Click Delete subgraph. Studio attempts to compose a new that doesn't include the you want to delete.

  4. A confirmation dialog appears that displays any errors that occurred:

    Dialog for confirming deletion of a subgraph

    If you're sure you want to delete the , enter its name and click Delete subgraph.

Viewing a field's originating subgraph

The Schema > Reference page in Studio displays a table of your 's types and . This table includes a Subgraph column, which lists the that define each type and :

Studio screenshot of Schema Reference, closeup of type row showing subgraph column

Clicking the link for a type or takes you to the line where it's defined in the corresponding :

Studio screenshot of Schema SDL, closeup of type definition in subgraph schema

If you're using the @contact directive to specify owner contact information for your , hovering over a subgraph name displays its contact information, enabling you to follow up with the appropriate team:

Studio screenshot showing subgraph contact tooltip in Schema Reference subgraph column

Viewing subgraph SDL

The Schema > SDL page in Studio displays the raw for each schema type associated with your —an , a , and .

From this page, you can:

  • View metadata about the composed , along with metadata about each (such its endpoint URL and most recent schema registration date)
  • Identify which define any type or in your API and share a link with team members
  • Search for types and s
  • Download a copy of your 's for local development
  • Filter out comments and deprecated for improved scanning

NOTE

Organization members with the Consumer role can only view the . Observers, Documenters, Contributors, Graph Admins, and Org Admins can view all schema types.

Contact info for subgraphs

You can use the @contact to add your team's contact info to a . This info is displayed in Studio, which helps other teams know who to contact for assistance with the subgraph:

Studio screenshot showing use of contact directive info as metadata in the Schema SDL view

The contact info includes a name (of a team or individual), along with an optional description and custom URL.

Adding the @contact directive to your subgraph

To use the @contact in your , you first need to define the directive in your schema. Add the following definition to each of your subgraph schemas:

schema.graphql
directive @contact(
"Contact title of the subgraph owner"
name: String!
"URL where the subgraph's owner can be reached"
url: String
"Other relevant notes can be included here; supports markdown links"
description: String
) on SCHEMA

You can now apply the @contact to each 's special schema object. If your schema doesn't already define this object, you can add it like so:

schema.graphql
extend schema
@contact(
name: "Acephei Server Team"
url: "https://myteam.slack.com/archives/teams-chat-room-url"
description: "send urgent issues to [#oncall](https://yourteam.slack.com/archives/oncall)."
)

Supported @contact fields

Name /
Type
Description
name

String!

Required. The name of the person, people, or team responsible for the .

url

String

The URL where the 's owner can be reached. This might be the URL of a chat room or forum, or it could be an email address.

description

String

Provides any additional helpful details about working with this or contacting its owner.

This supports Markdown-formatted links.

Known @contact limitations

  • To provide the @contact to Apollo, you must publish your by providing a local .graphql file as the --schema option of rover subgraph publish.
    • If you provide an result to the command instead, the @contact is not included in that result.

Viewing contact info

After you publish a that includes the @contact , the contact information is included in the metadata shown in Studio's Schema > SDL tab:

Studio screenshot showing use of contact directive info as metadata in the Schema SDL view

In the Schema > Reference tab, you'll also see a contact card when you hover over the link of a type or :

Studio screenshot showing subgraph contact tooltip in Schema Reference subgraph column

Schema tagging

In your , you can use the @tag to tag a type or with an arbitrary string value:

products.graphql
type Product {
id: ID!
name: String!
codename: String! @tag(name: "internal")
}

By default, these tags are removed from the API schema that's generated as part of . This means that tag information isn't visible to clients your .

If tag information should be visible to clients (for example, to help your API), you can enable this for a in Studio with the following steps:

  1. Go to the Settings page for your in .
  2. On the General tab, click Edit Configuration. The Update Build Configuration dialog appears.
  3. If you have a Federation 1 , enable the toggle for the @tag under Directives (this step isn't necessary for Federation 2 ).
  4. Under Build Settings, enable the toggle labeled Show all uses of @tag directives to consumers in Schema Reference and Explorer.
  5. Click Save.

After you make your @tag visible, you can view them inline with both the Schema and Explorer tabs in Studio.

In the Schema > Reference tab, tags are shown inline with each type and :

Studio screenshot showing tag directive in Schema Reference

Tags are also visible in the Explorer's Documentation tab:

Studio screenshot showing tag directive in Schema Reference

Supergraph support in the Explorer

The GraphOS Studio Explorer provides enhanced support for working with :

  • You can preview how your 's resolves data for an by inspecting the operation's query plan in the Response pane.
  • While you're building in the Explorer, you can see which each of your operation originates in by enabling subgraph hints from the Explorer's Settings tab.

Viewing composition errors

If a 's most recent set of failed to compose, a BUILD FAILED label is shown at the top of the 's page in Studio:

Studio screenshot showing a supergraph with a failed composition state

You can click this label to view the errors that must be resolved before can succeed:

Studio screenshot showing the composition error modal that is opened by clicking the build failed label
Previous
Graph exploration
Next
API keys
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company