Subgraph Failure & Partial Data

## The setting A federated graph is one client-facing schema composed from many independently deployed subgraph schemas. A **router** parses the client's document, works out which service owns which field, and issues its own requests — **subgraph fetches** — to those services, splicing the results back into one response shape. Take an 11-service legal case-file graph. A **Cases** subgraph owns `Case` and its `caseNumber`, `title` and `court`. **Parties** contributes `Case.parties`. **Billing** contributes `Case.billing`. Eight more services cover documents, deadlines, conflicts, audit and so on. A caseworker opens one screen: ```graphql query CaseOverview { case(id: "CASE-2019-4471") { caseNumber court { name } parties { role displayName } billing { unbilledHours lastInvoicedOn } } } ``` The plan is three fetches: Cases first, then Parties and Billing in parallel against the case key. Billing is having a bad afternoon and its fetch expires after 1,850 ms. ## What the client actually gets A response that arrives half-empty — one body, one status, two halves: ```json { "data": { "case": { "caseNumber": "2019/4471", "court": { "name": "Central District" }, "parties": [{ "role": "PLAINTIFF", "displayName": "Adeyemi Holdings" }], "billing": null } }, "errors": [ { "message": "Subgraph request failed", "path": ["case", "billing"] } ] } ``` Three things to read off it. The `data` key is **present** — execution began and mostly succeeded. The failed branch is `null`. And the `errors` list carries an entry whose `path` walks from the response root to the exact field that could not be filled, which is how a client tells *which* of eleven services let it down without knowing the topology. ## Why it is partial rather than total GraphQL distinguishes two failure classes. A **request error** — malformed syntax, a validation failure, a variable that cannot be coerced — means nothing executed; the response carries no `data` key at all, and over HTTP that is the case that earns a 4xx. A **field error** happens after execution started, when one field could not produce a value. A dead subgraph is the second kind: the document was valid, the plan ran, most of it worked. So the status stays a success and the body carries both halves. A client that treats any non-empty `errors` list as a total failure is throwing away a screen it could have drawn. ## Nullability decides the size of the hole The router cannot invent a `Billing` object; GraphQL has no default value for an output field. So the field becomes null, and the schema decides how far that null travels. `billing: Billing` leaves exactly the hole above. `billing: Billing!` cannot hold null, so the null climbs to the nearest nullable ancestor — possibly erasing `case` entirely, including the `caseNumber` and `parties` the healthy subgraphs already returned. Same outage, wildly different response, and the difference was written in the SDL months earlier. ## The silent variant Not every empty branch comes with an error. When the router resolves an entity by key, the subgraph returns one slot per key, and a slot may legitimately be null — an **unresolvable reference**: the service is healthy and simply has no such record. The client then sees `billing: null` with **no** entry in `errors`. That asymmetry is the practical diagnostic: a hole *with* an error entry is a failure, a hole *without* one is an absence. Any monitoring or client logic that reads "null means broken" will be wrong in one direction or the other. ## Who specifies this Be careful with attribution in an interview. The GraphQL specification defines the `data` / `errors` envelope, field errors and null propagation — it knows nothing about routers or subgraphs. Apollo Federation is a **composition** specification: it defines directives, entity keys and the reserved fields a subgraph exposes, and it does not define what a router does when a fetch breaks. Partial data plus a `path`-carrying error is a strong convention that mainstream routers converge on and that clients depend on — not a specified rule. Saying "the spec requires it" is the kind of confident wrong answer interviewers remember. ## What this changes downstream Because a service outage arrives as a normal 200 with a hole in it, ordinary HTTP monitoring sees nothing. Availability for a federated graph has to be measured on the *completeness* of responses — error entries per operation, grouped by the `path` prefix that identifies the failing branch — not on status codes. And clients must render per branch: draw the case, draw the parties, show a small unavailable marker where billing should be.