Composing Subgraphs into a Supergraph

What Composition Actually Merges

Composition takes one SDL file per subgraph and produces one supergraph SDL. It is a pure function: the same set of inputs always yields the same output, and if any input pair conflicts it refuses to produce output at all rather than shipping a graph that half works at runtime.

The inputs are plain schemas. The output carries more than clients ever see:

# input: catalog subgraph
type Product @key(fields: "id") { id: ID! name: String! }
type Query { product(id: ID!): Product }

# input: reviews subgraph
type Product @key(fields: "id") { id: ID! reviews: [Review!]! }
type Review { id: ID! rating: Int! }

# output: abridged supergraph SDL
type Product
  @join__type(graph: CATALOG, key: "id")
  @join__type(graph: REVIEWS, key: "id") {
  id: ID!     @join__field(graph: CATALOG) @join__field(graph: REVIEWS)
  name: String! @join__field(graph: CATALOG)
  reviews: [Review!]! @join__field(graph: REVIEWS)
}

Every @join__* annotation is routing data: which subgraph can resolve this field, which keys link them, which graph to call first. Two schemas sit inside that file:

• The supergraph — everything, join directives included. The gateway reads this.
• The API schema — the supergraph with join metadata and anything marked @inaccessible stripped away. This is what clients introspect.

That split is why adding a subgraph changes no client contract as long as the API schema is unchanged. It also means you can review ownership changes in a diff without confusing them with breaking API changes: join lines moving are refactors, API lines moving are releases.

The Four Composition Failures You Will See

Composition errors name the subgraph, type, and field responsible, so the job is reading them correctly rather than guessing.

The second one deserves a walkthrough because it is invisible until you read the error. Catalog declares type Position { x: Int! y: Int! } and a root field positionA; inventory declares type Position { y: Int! z: Int! } and positionB. Merging produces a Position with x, y, and z — but a query starting at positionA lands in catalog, which has never heard of z. The router would either error or silently drop the field, so composition refuses:

SATISFIABILITY_ERROR: field Position.z returned by positionA
cannot be resolved by subgraph "catalog"

The rule underneath all four: a merged type must be fully resolvable from every root field that can reach it. Making Position an entity (@key(fields: "id") declared in both subgraphs, with y marked @shareable since both resolve it) satisfies the rule — the router fetches id and x from catalog, then hops to inventory for z.

Composition also merges inputs and arguments by intersection: if the router might pass an argument to a subgraph that does not define it, the merge would drop it, so non-null disagreements fail loudly instead of becoming runtime surprises.

Publishing, Checks, and Ship Order

Composition is only build-time if somebody feeds it. The reliable shape is: each subgraph publishes its schema on merge, CI composes the proposed set, and the gateway consumes a versioned supergraph artifact.

# publish on every merge to main — the registry becomes the source of truth
rover subgraph publish storefront@prod \
  --name reviews --schema ./reviews/schema.graphql

# CI gate: compose proposed schemas, then diff against live field usage
rover subgraph check storefront@prod \
  --name catalog --schema ./catalog/schema.graphql

Publishing does three things a file in a git repo cannot. It versions each subgraph's schema so an incident from last Tuesday can be reproduced with the exact inputs that shipped. It gives composition a complete input set — a supergraph can only be built from subgraphs that have announced themselves. And it powers checks that compare a proposed change against real traffic: removing a field that still receives 3% of production operations fails the build instead of becoming an outage.

Ship order matters once composition is green. When an entity gains a second key, every subgraph contributing fields to that entity must declare it before composition succeeds — so roll the schema changes out to all owners first, publish them, let CI compose, then let the gateway pick up the new supergraph. Reversing that order produces a gateway that plans against keys half the fleet does not understand.

The discipline that keeps this tractable is monotonic evolution: add fields first, deprecate them in place, remove them only after usage drops to zero. Composition enforces structural compatibility; usage data from checks enforces social compatibility. You need both, because a schema can be perfectly composable and still break the mobile client that stopped sending the argument six months ago.