Federation & Composition

One call per item is an N+1 across services, where each call is a full subgraph request. The router instead collects every item's key into a single _entities call carrying a list of representations, so a 143-item list costs one request.

One schema and one endpoint. The client sends a single operation and gets one response, and nothing in that response says which service produced which field. The split across services is a server-side arrangement the caller never sees.

A query plan is the ordered set of subgraph requests a federation router derives from one client document. Each step is a complete GraphQL operation sent to exactly one subgraph, and the router merges the results into a single response.

The gateway holds the merge configuration: renames that resolve name collisions, plus delegation rules saying which field on one service's type is answered by calling which operation on another. The stitched services stay ordinary GraphQL servers, unaware of each other.

It marks the type as an entity: an object other subgraphs may reference. The fields argument is the selection set that identifies one instance, and the subgraph declaring it promises it can look an instance up from those fields alone.

One ordinary response carrying both halves: data holding everything the healthy subgraphs returned, and an errors entry whose path names the field the failed fetch should have filled. Partial data is the normal outcome, not an outage.

Each service publishes its own subgraph SDL. Composition merges those into one supergraph schema that also records which service owns each field. The API schema is that same graph with all federation machinery stripped out - the only one clients introspect.

A representation is a plain JSON object carrying __typename plus the fields of one key the subgraph declared for that entity type, and nothing else is guaranteed. It arrives as an untyped scalar, so the schema validates none of it.

Federation 2 assumes one owner per field so the router always knows where to fetch it and the answer never depends on the query plan. @shareable is the explicit opt-out: several subgraphs may resolve the field, and they promise to agree.

A data dependency. A fetch waits only when its input comes from an earlier fetch's result — usually the key values identifying its objects. Fetches whose inputs are already available run concurrently.

A federated router does not forward the client's HTTP request; it issues a fresh request per subgraph fetch. Identity travels only if the router is configured to copy the credential onto each one, and every subgraph must verify it itself.

The fields argument is a selection set, not a list. Space-separated names make one composite key from several fields; braces reach into a sub-object. All named fields together form one identity, and each must be resolvable in the declaring subgraph.

It reports a field in the merged graph that no query plan can reach: the router would have to enter the subgraph holding it, and no shared key allows that jump. Each schema is valid alone; the graph is not.

Team autonomy is the payoff: each team ships its slice of the schema without a shared release train. It is not a performance win — composition adds hops and failure modes. With few contributors on one cadence, one server still wins.

Because the router never calls the subgraph's own root fields for an entity another subgraph referenced. It calls _entities with key representations, so a check written inside a root-field resolver is simply not on that path.

Standard GraphQL introspection exposes directive definitions but never where directives are applied, so the federation directives that describe entities would be invisible. The _service field returns the subgraph's schema as text with those applications intact, and works where introspection is disabled.

A single aggregating server whose resolvers call the backends; a gateway that stitches remote GraphQL schemas using mapping held centrally; and a composed graph, where each service declares its own contribution and a composition step merges them.

Because the failed field was declared Non-Null. A null cannot sit there, so it climbs to the nearest nullable ancestor, discarding sibling fields the router had already collected from healthy services. Nullability at ownership seams sets the blast radius.

They record the routing metadata composition adds: a generated join__Graph enum lists each subgraph with its URL, @join__type says which subgraphs declare a type and with what key, and @join__field says which subgraph resolves each field.

Almost always the schema failed to compose. Composition is all-or-nothing, so no supergraph was produced and the router kept serving the last one that composed. The service is running new code while the graph still describes the old schema.

The router matches results to representations by position, not by identity. A reordered or shortened list silently attaches one entity's fields to a different entity. Return exactly one element per input, in order, with null where the entity could not be resolved.

Bound the list that produces it: require a paginated argument with an enforced maximum, and score document cost at the router before planning. Then chunk oversized representation lists and let the subgraph reject calls above its own cap.

The receiving subgraph declares the field with @override(from:) naming the subgraph it is taking over from; composition then routes every request for that field to the new one. Deploy the new implementation first, compose, verify, then delete the old field.

Only when the client reaches the entity through the exact field carrying the directive, and only if the resolver really returns the promised values. Reached by any other path, the router still fetches the field from the subgraph that owns it.

Depth, not count. End-to-end latency follows the longest chain of dependent fetches, because each round waits for the previous one to return. Six fetches in two concurrent rounds cost about two hops; six chained fetches cost six.

Treat the client-facing schema as the invariant and move one type at a time: register the remaining stitched gateway as a single subgraph of the composed graph, then lift types out of it, diffing the schema and replaying real traffic.

The header is unverified text, so the subgraph is trusting whatever can open a connection to it. It is safe only if nothing but the router can reach the subgraph and the router strips any copy the caller sent.

Nothing detects it. Composition takes uniqueness on faith, so colliding key values make two objects look like one: lookups return whichever row matched first, and any layer keyed on the identity serves one viewer the other's data.

Give the whole operation one deadline, derive each fetch's timeout from the budget left rather than a fixed constant, size it from that subgraph's own latency distribution, and propagate the deadline downstream so an abandoned fetch stops working.