Schema Composition

Learn how GraphOS combines subgraph schemas into a supergraph schema


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:

 note
GraphOS also provides a schema linter with composition specific rules to help you follow best practices. You can set up schema checks for your graph in GraphOS Studio or perform one-off linting with the Rover CLI. Check out the schema linting docs to learn more.

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:

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

GraphQL
Subgraph A
1type Event @shareable {
2  timestamp: String!
3}
GraphQL
Subgraph B
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.

 note
For examples of valid inconsistencies in field return types, see Differing shared field return types.

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!

Feedback

Forums