When does @provides in a federated subgraph actually save the router a fetch?

## The optimisation it expresses In a federated graph, a subgraph that returns another subgraph's entity normally returns only the key. The router then issues a second fetch to the owning subgraph, passing representations built from those keys, to fill in the fields the client actually asked for. That second fetch is the standard cost of splitting a type across services. `@provides` is how a subgraph says the second fetch is unnecessary *here*. It goes on the field that returns the entity, and it names the entity's fields this subgraph can already hand over: ```graphql # Reservations subgraph type Reservation @key(fields: "id") { id: ID! locker: Locker! @provides(fields: "address") } type Locker @key(fields: "id") { id: ID! address: String! @external } ``` Read literally: when a client walks from `Reservation` to `locker`, this subgraph will return `address` alongside the key, so plan for it here rather than calling the Lockers subgraph. That is usually possible because the reservation row already denormalises the locker address at booking time. ## The three conditions **The fields must be `@external` here.** `address` is not this subgraph's field; declaring it external says "I am naming someone else's field so I can talk about it". Without that, the declaration reads as a second implementation and runs into the ownership rules instead. **The owner must permit resolution in two places.** Once this subgraph returns `address`, that field is genuinely resolvable in two subgraphs, so in Federation 2 the owner must mark it shareable. This is the step people forget, and it fails at composition rather than at request time — which is the good outcome. **It is scoped to the one field path where it is written.** This is the condition that decides whether the optimisation shows up in production at all. The directive above says nothing about any other route to a `Locker`. A document that selects `locker(id: ...) { address }` at the root, or reaches a locker through `parcel { destinationLocker { address } }`, gets the ordinary owner fetch. So `@provides` pays off when one traversal dominates your traffic, and is close to dead weight when clients reach the entity a dozen ways. Before adding it, look at real operation traffic and ask which path carries the volume; adding it on a rarely-walked edge is complexity for nothing. ## Nothing checks the promise Composition validates the shape of the declaration — that the fields exist, are external here, and are shareable at the owner. It cannot validate the behaviour. At request time the router *skips asking the owner*, so whatever this subgraph puts in those keys is what the client gets. A concrete failure from a parcel-locker graph. The Reservations subgraph provided `Locker.address` from a denormalised column written at booking time. A locker was physically relocated; the Lockers subgraph was updated, the denormalised copies were not. Clients reaching the locker through a reservation received the old address for weeks, while the same field fetched from the root returned the correct one. No error, no log line, two truths in one graph — and the only signal was a support ticket. The list case is nastier. Put `@provides` on a field returning a list of entities and the promise applies to every element. In the same graph a `Locker.recentHolds` list grew without a bound as a locker aged; the resolver populated the provided field only for the elements it could serve from a warm cache and left the rest null. The router did not re-fetch — it had been told not to — so nulls flowed straight to clients, and because the provided field was non-null the nulls bubbled and erased whole branches of the response. The size of the blast radius was determined by how long the list had been growing, so it looked like a random, worsening intermittent bug. ## How to reason about it in an interview Say what it optimises (a fetch, on one path), what it costs (a second copy of the truth, plus a shareable field at the owner), and how it fails (silently, with stale or missing values, because skipping the owner fetch is the whole point). Contrast it with `@requires`, which points the other way: `@requires` lets a field in *this* subgraph demand sibling fields owned elsewhere, which forces the router to fetch from the owner *before* it can call here — adding a sequential step rather than removing one. `@provides` trades correctness risk for latency; `@requires` trades latency for expressiveness. A field that is expensive to keep in sync is a bad candidate for the first, and a field on a hot path is an expensive candidate for the second. When you do adopt it, treat the denormalised copy as a first-class integration: give it an owner, a refresh path and a reconciliation job that compares it against the owning subgraph, because the router will never do that comparison for you.