Working with supergraphs
in a federated architecture
A supergraph (also called a federated graph) is a graph composed of multiple subgraphs:
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
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 (
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 (
graphref) and subgraph introspection (
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
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
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.
|Rover version||Gateway version|
|<= v0.2.x||<= v0.38.x|
|>= v0.3.x||>= v0.39.x|