Skip to content
Journal

Web Development · API Design

GraphQL's N+1 Problem: Why DataLoader Exists

GraphQL resolvers hide N+1 queries differently than an ORM does. Why it happens per field, per request, and how DataLoader's batch-and-cache fixes it.

Abhishek Gupta

Abhishek Gupta

7 min read

A blue funnel pouring many colored marbles into a tray with sorting chutes and a small control panel

Sponsored

Share

Fifty posts, each with an author field, and your GraphQL server just ran 51 database queries to answer one request. That’s not a bug in your resolver logic. It’s what GraphQL’s execution model does by default, and it’s a different animal from the N+1 problem you’d hit with a plain ORM, which is exactly the gap DataLoader was built to close: batch every resolver call, don’t touch the loop.

Why GraphQL gets N+1 in a way that’s hard to spot in the code

A REST endpoint or a Django view has one clear place to add select_related or prefetch_related: the query that builds your response. GraphQL doesn’t have that place, because there’s no single query building the response. There’s a resolver per field, and the execution engine calls each one independently.

Here’s a minimal schema and resolver set:

const resolvers = {
  Query: {
    posts: () => db.posts.findMany(),
  },
  Post: {
    author: (post) => db.users.findUnique({ where: { id: post.authorId } }),
  },
};

Run this query:

query {
  posts {
    title
    author { name }
  }
}

GraphQL resolves posts once, getting back an array of 50 rows. Then, for every single post in that array, it calls the Post.author resolver, and that resolver has no idea it’s one of 50 identical calls happening in the same request. It just sees a post object with an authorId, and does what it’s told: look that one up. Fifty posts means fifty calls to db.users.findUnique, each a separate round trip, none of them aware the other 49 exist.

Comparison of total database queries for 50 posts with 8 unique authors: 51 queries without DataLoader versus 2 queries with DataLoader batching

Why “just eager-load it” doesn’t work here

With Django or Rails, the fix is straightforward because there’s a single loop you can see and modify: swap Post.objects.all() for Post.objects.select_related("author") and the ORM handles the join before the loop even starts. GraphQL’s resolver model doesn’t give you an equivalent hook. The Post.author resolver is written once and called independently for every post in every query that asks for it, whether that query returns 1 post or 10,000. There’s no “loop” in your code to wrap an eager-load call around, because GraphQL’s execution engine owns the iteration, not your resolver.

You could try to special-case it, checking inside the resolver whether other posts are also being resolved and batching manually, but that means threading request-scoped state through every resolver by hand. It works, technically, the same way manually managing memory works in a language with garbage collection. Nobody does it that way in production, because there’s a purpose-built tool for exactly this problem.

DataLoader: batch the calls, not the query

DataLoader, originally built at Facebook for this exact problem, sits between your resolver and your data source. Instead of resolving each author lookup immediately, it collects the requested IDs across a single tick of the event loop, then fires one batch function with all of them at once.

const DataLoader = require("dataloader");

const userLoader = new DataLoader(async (ids) => {
  const users = await db.users.findMany({ where: { id: { in: ids } } });
  const byId = new Map(users.map((u) => [u.id, u]));
  return ids.map((id) => byId.get(id));
});

const resolvers = {
  Post: {
    author: (post) => userLoader.load(post.authorId),
  },
};

The resolver code barely changed. db.users.findUnique(...) became userLoader.load(...). What changed is the execution: load() doesn’t fetch anything immediately. It queues the ID and hands back a promise. Because GraphQL calls all 50 Post.author resolvers synchronously within the same tick, all 50 IDs land in DataLoader’s internal queue before the event loop moves on to actually run any I/O. Once that tick ends, DataLoader fires its batch function exactly once, with all 50 (deduplicated) IDs, gets back one array of results, and resolves each individual pending promise with its matching row. Fifty resolver calls, one database query. The mechanism is timing, not a bigger change to your data-fetching logic.

The part that surprises people: request-scoped caching

DataLoader does something else by default that isn’t obvious from the batching alone: within a single request, calling load() with the same key twice only hits your batch function once. If a query asks for the same author on three different posts, DataLoader recognizes the repeated key and returns the cached in-flight or resolved promise for the other two calls instead of adding them to a new batch.

// Same request, three posts by the same author
userLoader.load(42); // queued
userLoader.load(17); // queued
userLoader.load(42); // returns the same pending promise as the first call(42), not a new one

// Batch function still only receives [42, 17], not [42, 17, 42]

This matters more than it looks like on paper, because real data isn’t evenly distributed. A blog with 50 posts from 8 authors means the naive N+1 version runs 50 redundant lookups where only 8 unique users exist. DataLoader collapses that to exactly 8, automatically, with no code beyond instantiating the loader per request.

One detail that trips people up: create a new DataLoader instance per request, not a shared global one. A loader that lives across requests will cache stale data for the lifetime of the process, since its cache has no expiration built in beyond the current DataLoader instance’s lifetime. Most GraphQL server setups create loaders inside the request context function specifically to avoid this.

// Apollo Server context, new loaders per request
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: () => ({
    userLoader: new DataLoader(batchGetUsers),
    postLoader: new DataLoader(batchGetPosts),
  }),
});

Batching doesn’t fix a badly indexed query underneath it

DataLoader controls how many times your resolver calls the database, not what that call costs once it gets there. If you’re still deciding whether GraphQL is the right fit for a given API in the first place, that tradeoff, more control over query shape versus more moving parts like this one, is a big part of how GraphQL compares to REST and tRPC. If batchGetUsers runs SELECT * FROM users WHERE id IN (...) against a table with no index on id as a primary key (unlikely, but substitute any non-indexed lookup column and it’s a real scenario), you’ve traded 50 slow queries for 1 slightly-less-slow query. Batching and indexing solve different halves of the same performance story, the same way fixing an N+1 query in a traditional ORM still leaves you needing a properly indexed join underneath the eager load. Check your batch functions’ generated SQL the same way you’d check any other hot-path query, with EXPLAIN ANALYZE or your database’s equivalent, before assuming DataLoader alone solved your latency problem.

The concrete takeaway

If your GraphQL server’s query count scales with the size of the list a client requests, you have the resolver version of N+1, and the ORM fix won’t reach it because there’s no single loop in your code to modify. DataLoader fixes the actual mechanism: it batches every load() call that happens within one tick into a single request to your data source, and caches repeated keys within that request for free. Add a loader for every field resolver that takes an ID and looks something up, keep the loaders scoped to the request, and check the batch query itself is indexed. That’s the whole fix, and it’s why every production GraphQL server you’ll find running at scale has DataLoader, or something functionally identical to it, sitting under the schema.

Frequently asked questions

What is the N+1 problem in GraphQL specifically?
It's what happens when a query asks for a list of N items and a nested field on each one, and the server resolves that nested field with a separate database call per item instead of one call for all of them. A query for 50 posts with each post's author becomes 1 query for the posts plus 50 more, one per post, for the author, because each post's resolver runs independently and doesn't know about the other 49 posts also asking for an author.
Isn't this the same problem as the ORM N+1 issue?
The symptom looks identical, one query becomes N+1, but the cause is different. An ORM's N+1 comes from a loop triggering lazy loads one at a time, and you fix it by telling the ORM up front to eager-load the whole loop. GraphQL's version comes from independent resolver execution, where the field resolver for `author` on post #3 has no built-in way to know that posts #1 through #49 are also asking for their authors in the same request. There's no loop to eager-load around; the fix has to batch across resolver calls instead.
How does DataLoader actually batch requests that happen independently?
DataLoader exploits how JavaScript's event loop works. When a resolver calls `loader.load(id)`, DataLoader doesn't fetch immediately. It queues the key and returns a pending promise. Because GraphQL's execution engine calls all 50 author resolvers within the same synchronous tick, all 50 keys land in DataLoader's queue before the event loop moves on to process any I/O. On the next tick, DataLoader fires one batch function call with all 50 keys, gets back 50 results, and resolves each individual promise with its matching result.
Do I need DataLoader for every field, or just the expensive ones?
Any field resolver that runs once per item in a list and hits a database, cache, or external API is a candidate. A resolver that only reads from data already attached to the parent object, like formatting a date field, needs nothing. The rule of thumb: if the resolver takes an ID and looks something up, batch it. If it just transforms data it already has in memory, don't bother.
Does DataLoader replace database-level optimizations like indexes or joins?
No, it sits at a different layer. DataLoader controls how many times your resolver code calls the database, turning N calls into 1 batched call per unique key set per request. What that one batched call does once it reaches the database, whether it uses an index, a join, or a full scan, is still entirely up to your query and your schema. Fix both: batch the calls with DataLoader, then make sure the batch query itself is indexed properly.

Sponsored

Sponsored

Discussion

Join the conversation.

Comments are powered by GitHub Discussions. Sign in with your GitHub account to leave a comment.

Sponsored