Schema Composition

In Apollo Federation, composition is the process of combining a set of subgraph schemas into a supergraph schema:

The supergraph schema includes all of the type and field definitions from your subgraph schemas. It also includes metadata that enables your router to intelligently route incoming GraphQL operations across all of your different subgraphs.

Supported methods

You can perform schema composition with any of the following methods:

Automatically with GraphOS

Apollo GraphOS performs composition automatically whenever you publish a subgraph schema. This enables your running router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available:

Manually with the Rover CLI

The Rover CLI supports a supergraph compose command that you can use to compose a supergraph schema from a collection of subgraph schemas:

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

To learn how to install Rover and use this command, see the Rover docs.

Breaking composition

Sometimes, your subgraph schemas might conflict in a way that causes composition to fail. This is called breaking composition.

For example, take a look at these two subgraph schemas:

❌

1type Event @shareable {
2  timestamp: String!
3}

1type Event @shareable {
2  timestamp: Int!
3}

One subgraph defines Event.timestamp as a String, and the other defines it as an Int. Composition doesn't know which type to use, so it fails.

Breaking composition is a helpful feature of federation! Whenever a team modifies their subgraph schema, those changes might conflict with another subgraph. But that conflict won't affect your router, because composition fails to generate a new supergraph schema. It's like a compiler error that prevents you from running invalid code. Refer to the Composition Rules Reference for details.

Next steps

Ready to compose your first supergraph? Get started with GraphOS!