Query Planning

## One document, many owners In a federated setup the graph a client sees is composed from several independently deployed schemas, each owned by a different team and service. A job-board graph might split into a Jobs subgraph (postings, titles, locations), an Employers subgraph (company profiles, logos, verification status) and an Applications subgraph (who applied to what, and when). The caller knows none of that. It writes one operation against the composed schema, where `Job.employer` looks like an ordinary field returning an ordinary object. Something has to bridge the two views, and that something is the router. **Query planning** is the part of its job that happens before any network call: read the incoming document, consult the composed schema for which service can supply each selected field, and produce a small program of subgraph requests that, executed in the right order, yields exactly the response the caller asked for. ## What a step actually is The unit of a plan is a **fetch**: one complete, valid GraphQL operation addressed to exactly one subgraph, with its own variables. That is worth stating plainly, because it is where most misconceptions start. The router does not forward the caller's document to every service and hope. It does not open a call per field. It *writes new documents* — usually a handful, sometimes just one — and each of them is an operation the receiving subgraph could have accepted from any ordinary caller. Steps come in two shapes. The first fetch of a plan is normally a **root fetch**: it enters a subgraph at a root field the caller actually named. Later fetches are normally **entity fetches**: the router already holds some objects, needs fields another subgraph owns, and asks for them through the federation entity entry point, passing those objects as representations — small stubs carrying `__typename` plus the key fields that identify each one. ## The shape of a plan A plan is a tree rather than a flat list, because concurrency matters. Fetches that depend on nothing from each other are grouped so the router can issue them at the same time; a fetch that consumes another's output sits after it. A third kind of node exists purely for addressing: it names a path inside data already fetched — say every element of `featuredJobs`, then that element's `employer` — so the following fetch knows which objects it is about. That node is why a single entity fetch can cover an entire list instead of one fetch per element. Router implementations differ in the vocabulary they print for these nodes; the structure they express is the same. ## A worked example Take the board's home screen, which asks for twelve featured postings with each employer's name and logo. The composed schema makes that one selection set. The plan is two fetches deep. The first fetch asks the Jobs subgraph for the twelve postings and, for each one, an *employer stub*. Note that last part carefully: the caller asked for `employer { name logoUrl }` and the Jobs subgraph can supply neither of those fields. What it can supply is the employer's identity. The second fetch takes all twelve stubs to the Employers subgraph in one entity request, and the router merges the returned names and logos back into the twelve job objects before serialising a response. ## What the caller sees, and does not The response carries the field names and aliases the caller wrote, and nothing else. It does not expose the plan, the intermediate stubs, the injected `__typename`, or which service answered what. That opacity is the point of a composed graph — and it is also why plan-shaped problems are invisible from the calling side and have to be diagnosed at the router, from its plan output or from tracing. ## Specification status Be careful with the word "specified" here, because interviewers listen for it. The GraphQL specification says nothing about routers, subgraphs or plans; as far as it is concerned there is one schema and one execution. Apollo Federation, as a composition specification, defines the directives a subgraph uses to declare its keys and ownership, and the entity entry point a subgraph must expose. Query planning is what a router *does* with that contract. The planning algorithm, the plan format, the node names it prints, and the choice it makes when two subgraphs could both answer a field are implementation behaviour and differ between routers. Saying "the specification defines the query plan" is a wrong answer; saying "the composition specification defines the contract, and the planner is one implementation of it" is the right one.