Managing graphs in Apollo Studio

This article describes Apollo Studio features for all graph types. For features specific to supergraphs, see also Supergraph-specific Studio features.

Creating graphs

To create a cloud supergraph, see the GraphOS quickstart.

To create a non-cloud graph (i.e., a self-hosted supergraph or a monograph), see this section.

Viewing graph details

After selecting an organization in Apollo Studio, click on a particular graph variant to view its README, schema, data, and settings. All of a Studio organization's members can access the data and settings for every graph that belongs to that organization.

The README page

When a user opens one of your graph's variants in Apollo Studio, its README page is shown:

Like the typical homepage for a Git repository, this page displays a Markdown-based README that you can edit with any content you like.

Each variant has its own README. If you edit one variant's README, those edits are not applied to other variants. Among other uses, this enables you to provide different information to external consumers in a public variant.

Supported Markdown

The README supports all basic Markdown syntax and most extended syntax (including tables, code blocks, and footnotes).

You can define a GraphQL code block with the following syntax:

1
```graphql
2
query MyQuery {
3
  users {
4
    id
5
    name
6
  }
7
}
8
```

This renders the code block with buttons you can use to copy an operation or open it in the Explorer:

README shortcodes

The README supports a set of shortcodes you can use to populate it with data that's specific to your variant, such as the graph's name and the variant's graph ref:

1
# Overview of {{ graph.name }}
2

3
Graph ref: {{ graph.ref }}

For a list of all supported shortcodes, click Graph shortcodes in the bottom-left corner of the README editor.

Exploring your schema

Apollo Studio provides helpful views for exploring your registered schema:

• The Explorer, which helps you build new operations against your graph
• The Schema page, which enables you to filter your schema's type and field definitions (and also view your schema's raw SDL)

The Explorer

Apollo Studio provides a powerful Explorer IDE that helps you visualize your graph and run queries against it. It's available from your graph's Explorer tab in Studio.

The Schema page

The Schema page lists the different kinds of definitions in your schema (objects, scalars, etc.):

Select a kind of definition to view a table of all corresponding types:

Each type definition in the table includes:

• The type's name
  • You can click the name to view additional details for the type (such as fields for an object, or possible types for a union).
• The type's description (if your schema includes one)
• Which subgraphs define the type (if you have a federated supergraph)
  • Users with the Consumer role can't view subgraph details.

Filtering your schema

The top of the Schema page provides a Filter Schema box you can use to find types and fields that match a set of filters:

Any filters you set remain active as you move between definitions on the Schema page.

You can filter your schema definitions by type/field name (as shown above), along with any combination of the following:

Filtering rules

• If you list multiple possible values in a single filter, those values use "OR" logic.
  • For example, if you filter by subgraph:products,reviews the result includes definitions from each subgraph.
• If you apply multiple types of filters, those filters use "AND" logic.
  • For example, if you filter by subgraph:products and returnType:Int, the result includes only definitions that fulfill both criteria.
• Currently, it isn't possible to use "AND" logic for multiple filters of the same type.
  • For example, it isn't possible to filter by subgraph:products "AND" subgraph:reviews to include only definitions that are present in both subgraphs.

Tracking schema changes

The Changelog page in Studio displays a timeline of changes made to your graph's schema:

Only schema changes that you publish to Studio are included in this timeline, which is one of the most important reasons to include schema publishing in your continuous delivery pipeline.

Managing access permissions

Public variants

You can enable public access for individual variants of your graph. If you do, anyone with that variant's public link can view the following pages for that variant in Studio:

• Home
  • This shows the variant's README.
• Schema
• Explorer
  • You can also embed the Explorer on your own webpage.

This enables consumers of your graph to learn about your graph's schema and any special usage information (such as authentication details) that you've documented in the public variant's README. They can also run properly authenticated operations against your graph with the Explorer.

People outside your organization can't view any other pages for a public variant (Fields, Operations, etc.), and they can never view any pages for private variants. New variants always start as private.

Making a variant public

1. Go to your variant's Settings page and open the This Variant tab.

2. Find the Public card and click Change:

   

3. Toggle your selection and click Save.

You can toggle the switch back to Off to make the variant private again.

After you make a variant public, you can click the variant's PUBLIC label at the top of Apollo Studio to get its public link:

Protected variants (Enterprise only)

If you have an Enterprise plan, you can designate particular variants of a graph as protected variants. Making a variant protected specifically affects the ability of users with the Contributor role to make certain changes to the variant:

• Contributors cannot push schema updates to a protected variant.
• Contributors cannot manage Explorer-related settings for a protected variant, like setting its URL.
• Graph API Keys with the Contributor permission cannot report usage metrics to your graph.

These are the only operations (other than creating new protected variants and creating new graphs) that can be performed by Contributors and not by Observers, so one way of thinking of protected variants are that they are variants where Contributors are treated as Observers.

Graph Admins and Org Admins can configure whether a variant is protected from the This Variant tab of the variant's Settings page.

Internal graph visibility (Enterprise only)

By default, graphs are visible to all members of your organization. If you have an Enterprise plan, you can set a graph to instead be visible only to members you invite.

You can configure visibility and grant your organization's members explicit access to your graph from the Access tab of your graph's Settings page.

Note that Org Admins can always see all graphs in your organization.

Dangerous actions

Transferring graph ownership

You can transfer a graph to a different GraphOS organization you belong to by visiting the graph's Settings page in Studio and changing the graph owner.

Deleting a graph

You can delete a graph from Studio by visiting its Settings page and clicking Delete Graph.