Apollo Federation @requires and @provides: cross-subgraph entity resolution

The cross-subgraph resolution problem

In a federated GraphQL supergraph, a subgraph often needs a field that another subgraph resolves to complete its own logic. Without explicit signals, the Apollo Router cannot determine whether to fetch the field from the owning subgraph, fall back to a resolver, or fail composition entirely. This ambiguity leads to broken supergraphs, repeated resolver calls, or composition errors that block deployment.

Useful takeaway

The @requires and @provides directives let a subgraph declare which external fields it needs to resolve a field and which fields it can contribute to an entity. The Apollo Router uses these signals during composition to build a query plan that fetches missing fields from the providing subgraph before invoking the requiring resolver—reducing round trips and avoiding composition failures.

How @requires and @provides work

When the router sees @requires(fields: "weight") on a field in subgraph A, it marks weight as @external for that field’s type. If subgraph B declares shippingEstimate @provides(fields: "shippingEstimate") on the same entity, the router knows to route the shippingEstimate fetch through B’s resolver before A’s resolver runs. The router’s query plan respects the dependency order, ensuring weight is available when shippingEstimate resolves.

Worked configuration example

The following minimal subgraph pair demonstrates the pattern. Subgraph A requires weight to resolve shippingEstimate; subgraph B provides that field.

# Subgraph A
type Product @key(fields: "upc") {
  upc: String! @external
  name: String!
  shippingEstimate: ShippingEstimate @requires(fields: "weight")
}

# Subgraph B
type Product @key(fields: "upc") {
  upc: String! @external
  weight: Float!
  shippingEstimate: ShippingEstimate @provides(fields: "shippingEstimate")
}

In composition, the router identifies that shippingEstimate in subgraph A is marked @requires(fields: "weight") and that subgraph B provides shippingEstimate on the same @key-declared Product. The router adds weight to the fetch list for subgraph B and ensures the query plan resolves weight before invoking A’s shippingEstimate resolver.

What the router does during composition

During apollo router supergraph compose, the router scans each subgraph’s SDL for @key and @external declarations. It cross-references @requires and @provides pairs. If subgraph A requires weight and subgraph B provides weight on the same @key-marked entity, the router includes weight in the query plan’s fetch list for subgraph B. When a concrete query arrives, the router sends a subgraph request for weight to B, waits for the response, then proceeds to evaluate A’s shippingEstimate resolver.

Limits and constraints

• Entity fields only: The directives apply only to fields on object types marked with @key. They cannot resolve scalar fields that are not part of an entity definition.
• No resolver replacement: The directives do not replace resolver logic inside a single subgraph. If a subgraph needs a field for business logic unrelated to entity resolution, use standard resolver patterns instead.
• @external required: Both the requiring and providing subgraphs must mark the shared entity field as @external in their respective SDLs; otherwise, composition fails.
• Federation v2+ required: The @requires and @provides directives are specific to Federation v2. Federation v1 does not support them, and attempting use with a v1-compatible gateway yields composition errors or silently ignored directives.

Common mistakes

1. Omitting @key on the entity. Without @key, the router cannot associate @requires/@provides with a specific entity, and composition rejects the supergraph.
2. Declaring @requires without the owning subgraph resolving the referenced field as @external. The dependent subgraph must declare the required field as @external; otherwise, the router cannot route the request.
3. Expecting @provides to override another subgraph’s authoritative definition. If two subgraphs declare the same field with @provides and no @requires chain, the router may raise a conflict or pick one based on schema precedence, not a deterministic override.
4. Using Federation v1 patterns. Target Federation v2 with the Apollo Router or a compatible gateway. Attempting @requires/@provides on a v1 setup yields no resolution behavior.

Practical verification

To confirm the setup works, run supergraph composition and inspect the generated query plan.

Command example

Run this in a terminal where the Apollo Router configuration file (e.g., apollo.yaml) is present and you have permissions to read the subgraph SDL files:

apollo router supergraph compose --config apollo.yaml

The command outputs a composed schema. Look for the queryPlan or directive section that lists which subgraph provides which field. A healthy composition will show weight attributed to subgraph B and shippingEstimate resolved by subgraph A after the dependency is satisfied. Risks: composition failure if @requires references a field not marked @external in the dependent subgraph, or if @provides pairs conflict across subgraphs.

To verify at runtime, issue a query that triggers the cross-subgraph chain:

{ product(upc: "some-upc-value") { shippingEstimate { cost } } }

Check the Apollo Router logs or use apollo router explicate to see the execution order. You should see the router fetch weight from subgraph B first, then resolve shippingEstimate in subgraph A.

Version assumptions

This behavior is supported in Apollo Federation v2 and requires the Apollo Router (or a gateway compatible with Federation v2). Apollo Server subgraphs should use @apollo/subgraph version 4.x or later matching the router/gateway generation. Federation v1 is deprecated; new implementations should target v2+.