Docs
Launch GraphOS Studio

Graph exploration

Explore and visualize your graph's types, fields, and relationships


As your grows, understanding its structure can become more difficult. Without understanding a schema's intricacies—particularly how relate to one another—development can become blocked or take wrong turns.

GraphOS Studio features

provides several ways of understanding and exploring your organization's graphs, including:

  • An editable README page that describes the to newcomers
  • The Schema page, which includes three distinct views, including schema visualization
  • The Explorer, which helps you build new against your
  • The Changelog, which displays all published changes

ⓘ NOTE

These features are available for all graph types. For features specific to , see Supergraph-specific Studio features. See Variant pages for the full list of Studio pages.

Viewing graph pages

After selecting an organization in , click a particular graph to view its pages.

Page permissions

With and , all Studio organization members have access to all pages, including Settings for all within the organization. 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 appears:

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 can't edit its README.

Each has its own README. If you edit one variant's README, those edits aren't 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. These shortcodes can populate the README with data specific to your , like 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.

The Schema page

A 's Schema page has three distinct views:

  • The Reference tab lets you filter your schema's type and definitions
  • The SDL tab displays your schema's raw
  • The Visualization tab provides a filterable, navigable, ical representation of your schema

Schema reference

The Reference tab on the Schema page lists the different kinds of definitions in your schema, for example, 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 isn't 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 .

Schema definition language

The SDL tab displays the raw () for each schema associated with your . For a , this is simply the graph's . also include a and . See Viewing subgraph SDL for more information.

Regardless of the type you're viewing, you can Copy the or download it in Raw or JSON format from this tab.

Schema visualization

The Visualization tab provides a ical representation of your schema's structure, including types, , and relationships. It can help clarify your understanding of your schema's design, so you can more easily identify potential issues and improve your data model.

Schema visualization in Studio

Use the buttons on the bottom of the page to:

  • Zoom in and out of the visualization
  • Copy a link to the visualization to share with organization members
  • Download an SVG or PNG of the visualization
  • Open and close the visualization Legend

On the top of the page, you can:

  • Click the double arrow to collapse or expand a searchable list of Types.

  • Click Show Filters to filter your visualization by root type, , or tag.

  • Click the Highlight dropdown to select particular types, tags, or to highlight.

    • Highlighting Unused types, Errors, Usage, or Latency, the visualization displays a heatmap whose Time range you can adjust in the bottom right of the screen.

      Visualization heatmap showing unused types and fields in a schema visualization
  • Click More to Collapse all fields or Hide particular , types, and nodes.

The Explorer

provides a powerful Explorer IDE that helps you visualize your graph and run queries against it. It's available from your graph's Explorer page in Studio. Refer to the Explorer docs to learn more.

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 in this timeline, which is one of the most important reasons to include schema publishing in your continuous delivery pipeline.

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

© 2024 Apollo Graph Inc.

Privacy Policy

Company