Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Resolvers and Execution

The N+1 Problem and DataLoader

Why nested GraphQL resolvers fire one query per item, and how batching with a per-request DataLoader cuts hundreds of queries down to two.

GraphQL resolvers are small and independent: each one knows how to fetch a single field. That is a strength, but it hides a trap. When you ask for a list and then a related object on every item, the naive resolvers run the related query once per item. A page that should need two database queries ends up running dozens, or thousands. This is the N+1 problem, and it is the most common performance bug in GraphQL servers.

Reminder: no real GraphQL server or database runs on this site. The runnable code is a stand-in: a fake database that counts queries and a hand-written loader that works the way the real dataloader package does in principle. The real libraries are shown read-only at the end.

Seeing the problem

Take this query and schema:

GRAPHQL
{
  posts {
    title
    author { name }
  }
}
GRAPHQL
type Query { posts: [Post!]! }
type Post { title: String!  author: Author! }
type Author { name: String! }

A typical resolver map has one resolver for Query.posts and one for Post.author:

JavaScript
const resolvers = {
  Query: { posts: () => db.query("SELECT * FROM posts") },
  Post: { author: (post) => db.query("SELECT * FROM authors WHERE id = ?", post.authorId) },
};

The executor calls Query.posts once (1 query) and gets N posts. Then it calls Post.author once per post (N queries). Total: N + 1. Each resolver is correct on its own; the cost only shows up in combination. The executor cannot merge the calls for you, because it treats every resolver as a black box.

One list, many queries

1 list query Fetch all posts.
N author queries One per post, often repeating the same author.
Slow page Latency grows with the list size.

A list of 100 posts costs 101 queries.

1 / 2

Batching and per-request caching

The fix is a small helper, usually called a DataLoader. Its two jobs:

  1. Batching. loader.load(id) does not fetch immediately. It remembers the key and returns a promise. When the current burst of synchronous work is finished (the next "tick" of the event loop), the loader calls one batch function with all the collected keys, for example SELECT ... WHERE id IN (...), and resolves each promise with its own result.
  2. Caching. If the same key is requested twice during the same request, the second call gets the same promise back. The author who wrote ten posts is fetched once.

The batch function has a strict contract: it receives an array of keys and must return an array of values of the same length and in the same order. A database does not return rows in the order of an IN list, so the batch function must reorder them and put an error or null in the slot of a missing key.

The stand-in below implements this in about twenty lines. The fake db records every query it receives, so you can compare the naive and the batched version, and also see the cache at work: the five posts have only three distinct authors.

Node.js Counting queries: naive resolvers versus a DataLoader

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Five posts cost six queries the naive way and two with the loader. The second query lists only three ids, not five, because the cache removed the duplicates before batching. With 500 posts and 20 authors the difference is 501 queries against 2.

One loader per request

A loader keeps a cache, so where you create it matters. If you create one loader at server start-up and share it between requests, it will happily serve a stale author name to every later request, and it can leak one user's data to another user when the loaded data depends on who is asking. The standard practice is to build all loaders when a request begins and put them in the context object, so every resolver in that request shares them and nothing outlives the request.

JavaScript
// Called once per incoming request.
function createContext(req) {
  return {
    user: req.user,
    loaders: {
      authorById: new DataLoader(batchAuthors),
      commentsByPostId: new DataLoader(batchCommentsForPosts),
    },
  };
}

const resolvers = {
  Post: { author: (post, args, ctx) => ctx.loaders.authorById.load(post.authorId) },
};

This is read-only (it assumes the real dataloader package). Context is explained in Resolvers.

The next stand-in shows the danger directly. One loader is shared by two "requests", and the author is renamed in between.

Node.js Why a loader must not outlive its request

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The shared loader keeps returning the old name until the process restarts. A per-request loader costs almost nothing to create and cannot go stale.

Never put a DataLoader in a module-level variable. It is a request-scoped object. The same rule applies to any cache that holds data which depends on the current user.

The same idea in Python

The technique is not tied to JavaScript. Python servers such as Strawberry and Graphene use the same pattern, usually with asyncio. The stand-in below uses an in-memory SQLite database and counts statements. A tiny loader collects ids with loop.call_soon and runs a single IN (...) query.

Python A batching loader in Python

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Six posts, one statement. The batch_authors function keeps the same contract as in JavaScript: one value per key, in key order, None where nothing was found.

Real libraries

Hand-writing a loader teaches the idea; in a real project use a maintained one. These are read-only here:

JavaScript
// Node.js: the "dataloader" package.
import DataLoader from "dataloader";

const authorLoader = new DataLoader(async (ids) => {
  const rows = await db.authors.findMany({ where: { id: { in: [...ids] } } });
  const byId = new Map(rows.map((r) => [r.id, r]));
  return ids.map((id) => byId.get(id) ?? new Error(`No author ${id}`));
});
Python
# Python: Strawberry ships its own DataLoader.
from strawberry.dataloader import DataLoader

async def load_authors(keys: list[int]) -> list[Author]:
    rows = await fetch_authors(keys)
    by_id = {a.id: a for a in rows}
    return [by_id[k] for k in keys]

loader = DataLoader(load_fn=load_authors)

Graphene projects commonly use the aiodataloader package for the same purpose. Other options exist at other layers: an ORM's eager loading (JOIN or IN prefetch), or looking ahead at the query's selection set in the parent resolver to fetch related rows up front. A loader is popular because it keeps each resolver independent: the resolver for Post.author does not need to know who called it.

To find N+1 problems, log or count database queries per request in development. A request whose query count grows with the list size is the signature. Put a test around it: see Testing GraphQL APIs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A query lists 50 posts and each post's author. With naive resolvers, how many queries does the author part cause?

    One author lookup per post. Together with the one query for the list the total is 51, which is where N+1 gets its name.
  2. 2. What must a DataLoader batch function return?

    The loader resolves each caller's promise with the value at the same index as its key, so the order and length must match.
  3. 3. Why should loaders be created once per request?

    A loader's cache holds loaded data. A shared one can serve outdated or user-specific values to later requests.
  4. 4. In which situation does the loader's cache help even when each key is requested only once per tick?

    Within a request a key can be needed from several places (for example the author of a post and of a comment). The second request gets the cached result.

Summary

  • N+1 happens when a nested resolver runs one query per parent item; the executor cannot merge them.
  • A DataLoader batches the keys requested in one tick into a single call and caches results by key.
  • The batch function returns one value per key, in key order.
  • Create loaders per request and keep them in the context; never share them globally.
  • Count queries per request to find N+1 problems; use a maintained library in production.

Next: Schema Design Best Practices.