Performance & N+1

Consider a query that lists books and, for each one, asks for its author:

If Query.books runs one query to fetch every book, and each Book.author resolver independently runs its own query to fetch that one book’s author, the total cost is one query for the list plus N more queries — one per book — for the authors. Double the list depth (books, each with an author, each author with a list of other books) and the same pattern compounds at every level, since Execution & Resolvers walks every item in a list field’s result and invokes that item’s own resolvers independently of its siblings. Nothing about this is a GraphQL specification defect — the execute stage is defined field by field precisely so each resolver can be simple and unaware of its siblings — but that same independence is what makes the naive version of a nested resolver expensive.

The root cause is that a per-item resolver, written the obvious way, only knows about the one parent item it was called with — it has no visibility into the fact that it is being called once per item in a list, and so no way to combine its own work with a sibling call’s work on its own:

For three books this is four total queries (one list query, three author queries); for a hundred books it is 101. The resolver code itself looks perfectly reasonable in isolation — the problem is only visible once you count how many times the runtime calls it during a single request.

DataLoader is a small, widely adopted utility (originally built at Facebook alongside GraphQL.js) that solves this by inserting a per-request layer between a resolver and its data source. Instead of a resolver fetching its own item immediately, it hands a key to a loader and receives a promise for that key’s value; the loader does two things no individual resolver call can do on its own:

Both behaviors are scoped to a single loader instance, and a loader instance is created fresh per request (typically inside the server’s context factory) so that one client’s cached results are never handed to a different client’s request. See the DataLoader reference implementation for the full API and its batch-scheduling behavior, and graphql.org/learn/performance for this pattern described from the schema-design side.

The diagram below contrasts the two call patterns for the three-book query above: the naive version issues one database round trip per book as each Book.author resolver runs independently, while the DataLoader version lets all three resolver calls enqueue their key first and dispatches a single batched round trip once every resolver in that tick has had a chance to call .load():

Three individual database round trips on the left collapse into one on the right, and any later resolver in the same request that loads an already-fetched id is served from the loader’s cache instead of triggering a fourth query.

Rewriting the naive Book.author resolver against a loader only changes where the fetch happens, not the resolver’s own shape — it still returns one author for one book, but now goes through a batching layer:

The resolver’s own code barely changed — context.db.findAuthorById(…​) became context.loaders.authorLoader.load(…​) — but the loader now guarantees the batching and per-request caching shown in the diagram above without the resolver itself needing to know how many siblings it has.

DataLoader fixes the number of round trips; it does not shrink what each round trip fetches. A resolver that always selects every column of a row, regardless of which fields the client actually asked for, still wastes bandwidth and database work on unrequested data. The execution info argument (Execution & Resolvers introduces its four resolver parameters) carries the parsed selection set for the current field, so a resolver can inspect which subfields were actually requested and look ahead to fetch only those columns or joins:

A query that only ever selects title never needs to load a book’s larger description column or join its author row at all — lookahead lets the resolver make that decision from the client’s own selection set instead of over-fetching by default. See graphql.org/learn/performance for lookahead described alongside the other techniques on this page.

The same principle applies to arguments, not just selected fields: a resolver that fetches an entire table and then filters, sorts, or slices it in application code pays for every row it discarded. Pushing a field’s args — a status filter, a sortBy, a pagination cursor and page size — straight into the underlying query’s own WHERE/ORDER BY/LIMIT clauses means the datastore itself does the discarding, and only the rows the client will actually see ever cross the wire between the resolver and its data source:

Pagination covers cursor-based pagination itself — the first/after argument shape and the PageInfo/edges response shape — in depth; this page only notes that pushing those arguments down to the datastore, rather than paginating an already-fully-loaded array in memory, is what keeps a paginated field’s cost proportional to the page size instead of the table size.

Because a client chooses its own selection set, a single query can request a deep selection (an object nested many levels below the root) or a wide one (a list field with a large page size, or many aliased copies of the same expensive field) without the server having agreed to that shape in advance. Even with batching and datastore pushdown in place, a sufficiently deep or wide query still does proportionally more resolver work and returns a proportionally larger response than a shallow one — batching reduces the number of round trips a given shape costs, it does not make an arbitrarily large shape free. Bounding how deep or wide a client is allowed to go is a demand control concern rather than a resolver-performance one: Security & Demand Control covers depth limiting, breadth/alias limiting, and query cost analysis for rejecting an overly expensive query before it executes at all.

Everything above reduces how much work the server does to produce a response; compressing that response before it goes over the wire reduces how long it takes to deliver it, independently of how it was produced. A GraphQL response is ordinary JSON served over HTTP, so the same Content-Encoding negotiation any HTTP API uses applies unchanged — a client sends Accept-Encoding: gzip, br, and a server (or an intermediary proxy or CDN in front of it) compresses the response body accordingly:

Large GraphQL responses — a wide list selection, or many aliased fields — compress especially well because JSON’s repeated key names and structural punctuation are exactly the kind of redundancy general-purpose compression removes; enabling it is usually a one-line server or reverse-proxy setting rather than anything GraphQL-specific. See MDN’s Content-Encoding reference for the header semantics and the gzip/br (Brotli) encodings themselves.