Rover supergraph commands

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:

1
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:

1
subgraphs:
2
  films:
3
    routing_url: https://films.example.com
4
    schema:
5
      file: ./films.graphql
6
  people:
7
    routing_url: https://people.example.com
8
    schema:
9
      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):

1
subgraphs:
2
  films:
3
    routing_url: https://films.example.com
4
    schema:
5
      file: ./films.graphql
6
  people:
7
    routing_url: https://example.com/people
8
    schema:
9
      subgraph_url: https://example.com/people
10
  actors:
11
    routing_url: https://localhost:4005
12
    schema:
13
      graphref: mygraph@current
14
      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:

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

Gateway compatibility

The rover supergraph compose command produces a supergraph schema by using composition functions from the @apollo/subgraph 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.

Fetching a supergraph schema from Apollo Studio

You can use Rover to fetch the supergraph schema of any federated Studio graph and variant it has access to. Run the supergraph fetch command, like so:

1
rover supergraph fetch my-graph@my-variant

The argument my-graph@my-variant in the example above specifies the ID of the Studio graph you're fetching from, along with which variant you're fetching.