DataLoader: batching across resolver trees

A GraphQL query for me { posts { author { name } } } on 50 posts triggers 1 + 50 author lookups. The ORM eager-load approach cannot help here — the data need is scattered across 50 independent resolver calls, not concentrated at one query site. DataLoader is the structural fix.

Why ORM eager loading is not enough for GraphQL

ORM eager loading (includes, select_related, joinedload) works by declaring relationships at the query construction site. You write one query with relationships declared up front. In a GraphQL server, there is no single query construction site — each resolver runs independently for each parent object. There is no natural place to say “by the way, I will also need the author for all of these posts.”

When 50 post resolvers each call db.user.findUnique({ where: { id: authorId } }), the ORM does not know they are all asking for the same kind of data. It fires 50 queries.

DataLoader solves this by moving batching to the request scope, not the query scope.

How DataLoader works

Facebook open-sourced DataLoader in 2015 alongside GraphQL.js. The mechanism:

1. A DataLoader instance is created once per request (not per call).
2. Any code in the request calls loader.load(id), which returns a Promise and queues the id internally — it does not execute a query.
3. When the current synchronous work finishes and the event loop reaches its next tick, the loader fires one batched query: SELECT * FROM users WHERE id IN (all queued ids).
4. The loader distributes results to each waiting Promise in order.

// Create once per request (e.g., in GraphQL context)
const userLoader = new DataLoader(async (ids) => {
  // ids is the batch: all IDs queued since last tick
  const users = await db.user.findMany({
    where: { id: { in: ids } },
  });
  // Must return results in the same order as ids
  return ids.map(id => users.find(u => u.id === id) ?? null);
});

// In a Post resolver — called 50 times for 50 posts
const resolveAuthor = async (post) => {
  return userLoader.load(post.authorId);
  // Does NOT query immediately — queues the ID
};
// After all 50 resolvers have queued their IDs,
// DataLoader fires one query:
// SELECT * FROM users WHERE id IN (1, 2, ..., 50)

Three properties DataLoader provides:

1. Automatic batching — many load(id) calls in one event-loop tick become one query.
2. Automatic caching — load(id) called twice in the same request returns the cached result without a second query.
3. Request scope — the cache is scoped to the request object, so stale data does not leak between requests.

GraphQL four-level N+1

The shape compounds with nesting depth. For a query me { teams { projects { members { name } } } }:

• teams resolver: 1 query
• projects resolver (per team): N queries
• members resolver (per project): N×M queries
• name: included in members, no extra queries

Total without DataLoader: 1 + N + (N×M) queries. With DataLoader per type: 4 queries total — one per type per request.

// Each loader batches one type
const teamLoader = new DataLoader(ids => batchLoadTeams(ids));
const projectLoader = new DataLoader(ids => batchLoadProjects(ids));
const memberLoader = new DataLoader(ids => batchLoadMembers(ids));

// Each resolver just calls the loader:
const resolveTeams = (user) => teamLoader.load(user.id);
const resolveProjects = (team) => projectLoader.load(team.id);
const resolveMembers = (project) => memberLoader.load(project.id);

Impact: query count drops 100–1000x depending on fan-out depth. p99 drops from 1.4 s to ~150 ms for a typical four-level query.

DataLoader vs ORM eager loading: when to use each

DataLoader is more powerful and more complex than ORM eager loading. Choose based on where the data needs originate:

• Known shape at query site → ORM eager loading. One declaration, ORM handles it.
• Data needs scattered across many code paths → DataLoader. Batches across resolver trees or module boundaries.

The deciding question: “do I know at one place in the code what all the data needs are?” If yes, eager load. If no, DataLoader.