How DataFetcher and DataLoader Work

DataFetcher is the resolver primitive in graphql-java — every single field in your schema has one, whether you wrote it explicitly or Spring registered it through @QueryMapping. For simple scalar fields like title, the default PropertyDataFetcher calls the getter. For relational fields like Book.author, you provide a custom fetcher.

The N+1 performance trap:

• The performance trap shows up on list queries: if you fetch fifty books and each book's author field fires its own database call, you get fifty-one total queries — one for books, fifty for authors
• Each resolver runs independently with no awareness of the other pending loads at the same level — this is by design, and DataLoader is the intended fix

How DataLoader solves it:

• Instead of hitting the database immediately, each resolver calls authorLoader.load(id) and gets back a CompletableFuture; the engine collects all load calls during one execution level, then dispatches them as a single batch — one WHERE id IN (...) replaces fifty singleton selects
• The engine's level-by-level execution creates the batching window: all DataFetchers at one depth complete before the next depth dispatches, which is why DataLoader can collect keys across siblings

The non-negotiable ordering rule:

• Your batch function must return results in the same order as the input key list — DataLoader matches results to parents by position, not by key lookup
• If you return them in database sort order instead, data silently attaches to the wrong parent objects — it looks like corruption but it's an ordering bug

Per-request caching:

• DataLoader caches within the request — two books sharing the same author ID produce one lookup; but if a mutation updates that author mid-request, call loader.clear(id) explicitly to prevent stale data

I recommend wiring DataLoader for every @SchemaMapping that resolves a related entity from the start — retrofitting is significantly harder after the N+1 problem is discovered in production.