/
Launch Apollo Studio

Federated graphs in Studio


A federated graph (also known as a supergraph ) is a graph that’s composed of multiple individual subgraphs:

Supergraph (A + B + C)
Subgraph A
Subgraph B
Subgraph C

Each subgraph represents an underlying service or set of services that provide their own GraphQL API. Different subgraphs are often owned by different teams in an organization.

Apollo Studio provides tools to help multiple teams collaborate on a federated graph and its subgraphs.

Viewing a field's originating subgraph

The Schema > Reference tab in Studio displays a table of your federated schema’s types and fields. This table includes a Subgraph column:

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

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

Viewing subgraph SDL

The Schema > SDL tab in Studio displays the raw SDL of your federated graph’s schema, along with the schema of each subgraph.

From this tab you can:

  • View metadata about the composed graph and each subgraph (such as endpoint URL and the most recent schema registration date)
  • Identify the originating subgraph for any type or field in your API and share a link with team members
  • Search for types and fields
  • Download a copy of your subgraph’s SDL for local development
  • Filter out comments and deprecated fields for improved scanning

Subgraph contact info

You can use the @contact directive to specify contact information for a particular subgraph, such as a name and URL. This information is visible in Studio, which helps your organization members find who to contact for assistance with a particular type or field:

Adding the @contact directive to your subgraph

To add the @contact directive to your schema, you first need to define the directive. 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 directive to the special schema object. Many schemas don’t include this object because it’s not required, but you can add it like so:

schema.graphql
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)."
) {
  query: Query
}

Note that the schema object can’t be empty, so you need to add the query field as shown above if it isn’t already present.

Supported @contact fields

NameTypeDescription
nameString!The name of the person, people, or team responsible for the subgraph. Required.
urlStringThe URL where the subgraph’s owner can be reached. This might be the URL of a chat room or forum, or it could be an email address.
descriptionStringProvides any additional helpful details about working with this subgraph or contacting its owner. This field also supports markdown links.

Known @contact limitations

  • To provide the @contact directive to Apollo, you must register your schema using the --localSchemaFile option of apollo service push. If you use the --endpoint option instead, directives are not included in the registered schema.

  • Similarly, you cannot provide your @contact directive to Apollo via schema reporting. This registration method also does not include directives.

  • If your subgraph doesn’t already have a schema object, you need to add one to use the @contact directive. The schema object cannot be empty, so you need to include at least one field in it (most commonly query: Query). If you do provide the Query type like this, it needs to include at least one field in your subgraph’s schema. If your subgraph’s Query type is empty, you need to add a dummy field for the SDL to be valid:

    schema.graphql
    @contact(...)
    schema {
      query: Query
    }
    
    extend type Query {
      _dummyField: Boolean
    }

Viewing contact info

After you register a subgraph schema with the @contact directive, the contact information is included in the metadata shown in Studio’s Schema > SDL tab:

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

Federation support in the Explorer

The Apollo Studio Explorer provides enhanced support for working with federated graphs:

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

Viewing composition errors

Studio displays a Federated label next to the name of a federated graph. If a federated graph has composition errors, you can click the label to view the errors that must be resolved before composition can succeed.

Learn more about composition errors

Edit on GitHub