Docs
Launch GraphOS Studio

Managing graphs in GraphOS Studio


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

Creating graphs

To create a cloud supergraph, see the GraphOS quickstart.

To create a non-cloud graph (that is, a self-hosted or a ), see this section.

Viewing graph details

After selecting an organization in , click a particular graph 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.

💡 TIP

Enterprise accounts can set member roles to configure fine-grained access for individual members of their organization.

The README page

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

GraphQL codeblock in README

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

NOTE

Only organization members with the Org Admin, Graph Admin, Contributor, or Documenter role can edit a 's README. If a variant is protected, Contributors cannot edit its README.

Each variant has its own README. If you edit one '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 code block with the following syntax:

```graphql
query MyQuery {
users {
id
name
}
}
```

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

GraphQL codeblock in README

README shortcodes

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

# Overview of {{ graph.name }}
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

provides helpful views for exploring your registered schema:

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

The Explorer

provides a powerful Explorer IDE that helps you visualize your 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, , etc.):

Schema page list of type definitions in Studio

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

Schema page list of type definitions in Studio

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 for an object, or possible types for a union).
  • The type's description (if your schema includes one)
  • Which define the type (if you have a federated )
    • Users with the Consumer role can't view details.
Filtering your schema

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

Schema page filter box and dropdowns

💡 TIP

  • Click the arrow button to the left of the filter box to show/hide the filter selection dropdowns.
  • Click the button to the right of the filter box to copy a shareable URL of your currently active set of filters (you can also copy your browser's address bar directly).

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

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

FilterDescriptionExample
subgraph

Include results defined in any of the specified .

Valid only for federated .

subgraph:products,reviews

tag

If your uses the @tag , include results that have a @tag with any of the specified names. If viewing a table of objects, also include objects with at least one that has a specified @tag.

If your doesn't use the @tag , this filter is not available.

tag:internal,experimental

directive

Include results that have any of the specified applied. If viewing a table of objects, also include objects with at least one that has a specified directive.

directive:deprecated,unused

returnType

Include results with any of the specified return types. If viewing a table of objects, include objects with at least one that has a specified return type.

This filter includes all that return a particular type, regardless of each field's nullability or whether it returns a list. For example, if you specify returnType:Int, the filter includes that return any of Int, Int!, or [Int].

returnType:Int,String

argument

Include results that take a with any of the specified names. If viewing a table of objects, include objects with at least one that takes a specified argument.

argument:offset,limit

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

Tracking schema changes

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

Schema Changelog tab

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 of your . If you do, anyone with that variant's public link can view the following pages for that in Studio:

  • Home
    • This shows the 's README.
  • Schema
  • Explorer

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

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

Making a variant public

NOTE

Only organization members with the Org Admin or Graph Admin role can toggle a 's public visibility.

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

  2. Find the Public card and click Change:

    Toggle public variant in Studio
  3. Toggle your selection and click Save.

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

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

Public variant label in Studio

Protected variants (Enterprise only)

If you have a GraphOS Enterprise plan, you can designate particular of a as protected variants. A protected limits the capabilities of users with the Contributor role to make certain changes to the :

  • Contributors cannot push schema updates to a protected .
  • Contributors cannot manage Explorer-related settings for a protected , such as setting the variant's endpoint URL.
  • API Keys with the Contributor role cannot report usage metrics for a protected .

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

Internal graph visibility (Enterprise only)

💡 TIP

For external visibility, see Public variants.

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

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

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

Dangerous actions

Transferring graph ownership

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

Deleting a graph

⚠️ CAUTION

Deleting a graph cannot be undone!

If you delete a cloud , all its -hosted are deprovisioned.

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

Previous
Updating your graph
Next
Supergraph-specific Studio features
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company