Working with supergraphs

A supergraph (also called a federated graph) is a graph composed of multiple subgraphs:

Rover commands that interact with supergraphs begin with rover supergraph. These commands primarily deal with composition of a supergraph schema that adheres to the core schema specification.

Composing a supergraph schema

You can use the supergraph compose command to compose a supergraph schema based on a provided subgraph configuration file:

rover supergraph compose --config ./supergraph.yaml

Configuration

The supergraph compose command's --config option expects the path to a YAML file that contains a list of all subgraphs:

subgraphs:
  films:
    routing_url: https://films.example.com
    schema:
      file: ./films.graphql
  people:
    routing_url: https://people.example.com
    schema:
      file: ./people.graphql

In the above example, The YAML file specifies each subgraph's public-facing URL (routing_url), along with the path to its schema (schema.file).

It's also possible to pull subgraphs from various sources and specify them in the YAML file. For example, here is a configuration that specifies schema using Apollo Registry refs (subgraph, graphref) and subgraph introspection (subgraph_url):

subgraphs:
  films:
    routing_url: https://films.example.com
    schema:
      file: ./films.graphql
  people:
    routing_url: https://example.com/people
    schema:
      subgraph_url: https://example.com/people
  actors:
    routing_url: https://localhost:4005
    schema:
      graphref: mygraph@current
      subgraph: actors

Output format

By default, supergraph compose outputs a supergraph schema document to stdout. This will be useful for providing the schema as input to other Rover commands in the future.

You can also save the output to a local .graphql file like so:

# Creates prod-schema.graphql or overwrites if it already exists
rover supergraph compose --config ./supergraph.yaml > prod-schema.graphql

For more on passing values via stdout, see Using stdout.

Gateway compatibility

The rover supergraph compose command produces a supergraph schema by using composition functions from the @apollo/federation package. Because that library is still in pre-1.0 releases (as are Rover and Apollo Gateway), some updates to Rover might result in a supergraph schema with new functionality. In turn, this might require corresponding updates to your gateway.

Apollo Gateway fails to start up if it's provided with a supergraph schema that it doesn't support. To ensure compatibility, we recommend that you test launching your gateway in a CI pipeline with the supergraph schema it will ultimately use in production.

We aim to reduce the frequency at which these paired updates are necessary by making supergraph additions backwards compatible. We will note changes that require corresponding Apollo Gateway updates clearly in the Rover Release Notes, and we'll also update the following compatibility table.