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

Fetching a supergraph schema from GraphOS

supergraph fetch

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

1
rover supergraph fetch my-supergraph@my-variant

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

Composing a supergraph schema

supergraph compose

You can use the supergraph compose command to

1
rover supergraph compose --config ./supergraph.yaml

You can also pass config via stdin:

1
cat ./supergraph.yaml | rover supergraph compose --config -

YAML configuration file

The supergraph configuration file (often referred to as supergraph.yaml) includes configuration options for each of your

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

A single configuration file can pull subgraph schemas from a variety of sources. For example, here's a configuration that includes subgraph schemas from three different types of sources:

1
federation_version: =2.3.2
2
subgraphs:
3

4
  # Local .graphql file
5
  films:
6
    routing_url: https://films.example.com
7
    schema:
8
      file: ./films.graphql
9

10
  # Subgraph introspection
11
  people:
12
    routing_url: https://example.com/people  # <- can be omitted if the same as introspection URL
13
    schema:
14
      subgraph_url: http://127.0.0.1:4002
15
      introspection_headers:  # Optional headers to include in introspection request
16
        Authorization: Bearer ${env.PEOPLE_AUTH_TOKEN}
17

18
  # Apollo Studio graph ref
19
  actors:
20
    routing_url: http://localhost:4005  # <- can be omitted if matches existing URL in Studio
21
    schema:
22
      graphref: mygraph@current
23
      subgraph: actors

Variable expansion

The supergraph.yaml file supports variable expansion using

Output format

By default, rover supergraph compose outputs a

You can save the schema 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 --output prod-schema.graphql

Federation 2 ELv2 license

The first time you use Federation 2 composition on a particular machine, Rover prompts you to accept the terms and conditions of the

The ELv2-licensed supergraph plugin (built from

Setting a composition version

Whenever you run rover supergraph compose, Rover automatically downloads the composition library for the given federation version you specified either in your

The command supports both Federation 1 and Federation 2 composition. Federation 1 and Federation 2 use different composition algorithms, which are implemented in different libraries:

• Federation 1:
  @apollo/federation
• Federation 2:
  @apollo/composition

Automatic updates

If you don't specify a federation_version in supergraph.yaml (which will be required in future versions), Rover determines which version to use according to the following logic:

The latest federation library version is stored in

This auto-update flow will cause issues if you don't update your router version prior to updating your composition pipeline. We strongly recommend always specifying an exact federation_version.

Preventing auto-updates

In some cases, you might want Rover to skip updating its composition library to the latest version. For example, you might have a slow or nonexistent network connection.

In these cases, you can pass the --skip-update flag to rover supergraph compose. If you provide this flag, your supergraph.yaml file must specify a federation_version (which is recommended regardless).

Legacy Rover versions

Versions of Rover prior to v0.5.0 support only Federation 1 composition, via the

We recommend updating to the latest version of Rover as soon as possible. If you're still using a legacy version, see the following compatibility table regarding support for different versions of the @apollo/gateway library: