What is the N+1 problem in GraphQL resolvers?

Consider a schema where Query.posts returns a list of Post objects and each Post has an author: User field. The naive resolvers are simple: posts runs one query such as SELECT * FROM posts LIMIT 50, and Post.author runs SELECT * FROM users WHERE id = ? using the post's author_id.

The trouble comes from how GraphQL executes. The engine resolves fields one at a time. Once posts returns its list, the engine calls the author resolver separately for each post. Each call knows only about its own parent object, so it has no way to see that 49 sibling calls are about to ask for the same kind of row. Every call issues its own query.

Illustrative estimate (assumed inputs: 50 posts, one query per resolver call, no caching):

  • Naive resolvers: 1 query for posts + 50 queries for authors = 51 queries
  • Batched resolvers: 1 query for posts + 1 query using WHERE id IN (...) = 2 queries

The problem grows with query depth. If you add comments under each post and author under each comment, the query count multiplies at every level of the tree.

This matters most to the engineers who own latency and database capacity. Each extra query adds a network round trip, and that cost grows with list size. Each one also holds a pool connection, so a single popular query can use up the pool. Clients choose the shape and size of the queries they send, so one innocent-looking request can turn into hundreds of database calls.

// Naive resolvers for: type Query { posts: [Post!]! }  type Post { author: User! }
// `db.query` is a placeholder for any SQL client that returns rows.
import { db } from './db';

let queryCount = 0; // counts DB round trips for this request (demo only)

async function run(sql: string, params: unknown[] = []) {
  queryCount++;
  return db.query(sql, params);
}

export const resolvers = {
  Query: {
    // Runs once per request: 1 query.
    posts: () => run('SELECT * FROM posts LIMIT 50'),
  },
  Post: {
    // Runs once PER POST. The engine calls this for each parent separately,
    // and each call only sees its own `post`, so it cannot combine work
    // with its 49 siblings. 50 posts => 50 separate queries.
    author: async (post: { author_id: number }) => {
      const rows = await run('SELECT * FROM users WHERE id = $1', [post.author_id]);
      return rows[0];
    },
  },
};

// Client query that triggers it:
//   { posts { title author { name } } }
// After this request, queryCount === 51 (1 for posts + 50 for authors).
// A batched version would issue one query instead of the 50 author queries:
//   SELECT * FROM users WHERE id = ANY($1)   -- queryCount === 2

Naive posts-and-authors resolvers where Post.author runs once per post, producing 1 + 50 = 51 queries for a 50-post list (illustrative count), compared with 2 queries when the author lookups are batched.

How does DataLoader batching work?

DataLoader does not reduce the number of load(key) calls your resolvers make. It defers them. When a resolver calls load(key), DataLoader records the key, returns a Promise, and does nothing else yet. Once the current tick of the event loop finishes, it passes every key it collected to your batch function in a single call. That one call becomes one query, such as WHERE id IN (...). When it resolves, DataLoader routes each result back to the Promise of the caller that requested it.

This works because GraphQL executes resolvers breadth-wise. Resolving a list field runs the child resolvers for every item in that list, and they all start before any of them finish waiting on I/O. So the 50 author resolvers for 50 posts call load() within the same tick, and DataLoader groups them without any coordination between resolvers.

Flow for one list field:

  • Resolvers: post[0].author → load(7), post[1].author → load(3), post[2].author → load(7), …
  • Tick boundary: the current tick ends and DataLoader dispatches the collected keys.
  • Batch function: called once with [7, 3, …] and runs one query.
  • Fan-out: results are matched back by key, and every pending Promise resolves.

load(7) was called twice in that example, but key 7 is sent to the batch function only once. DataLoader memoizes by key: a repeated key gets back the same Promise it handed out the first time. This cache is held in memory on the loader instance. It does not expire entries, it is not shared between requests, and it is not a distributed cache. It removes duplicate work within a single request, and that is all it does.

 Request scope: one authorLoader instance, created per request
+---------------------------------------------------------------------+
|  post[0].author      post[1].author      post[2].author     ...     |
|  load(7)             load(3)             load(7)                    |
|     |                   |                   |                       |
|     v                   v                   v                       |
|  +---------------------------------------------------------------+  |
|  | memo cache (per request, in memory, no expiry)                |  |
|  | 7 -> Promise A   3 -> Promise B   7 -> Promise A (reused)     |  |
|  | pending keys: [7, 3, ...]  (7 queued once)                    |  |
|  +---------------------------------------------------------------+  |
|                                  |                                  |
| - - - - - - - - - - end of tick: dispatch - - - - - - - - - - - - - |
|                                  v                                  |
|              +----------------------------------------+             |
|              | batch function: called once            |             |
|              | batchFn([7, 3, ...])                   |             |
|              +----------------------------------------+             |
|                                  |                                  |
|                                  v                                  |
|              +----------------------------------------+             |
|              | one query: WHERE id IN (7, 3, ...)     |             |
|              +----------------------------------------+             |
|                                  |                                  |
|                results matched back by key (fan-out)                |
|              +-------------------+-------------------+              |
|              v                   v                   v              |
|        Promise A (7)       Promise B (3)       Promise A (7)        |
|      post[0] resolves    post[1] resolves    post[2] resolves       |
+---------------------------------------------------------------------+

Sibling author resolvers call load() in the same tick, the per-request memo cache gives the repeated key 7 the same Promise, and at the tick boundary DataLoader makes one batch function call whose results fan out by key to every waiting resolver.

How do you write a batch function that honors the contract?

The batch function receives an array of keys and must return a promise of an array with the same length and the same order. The database guarantees neither. A WHERE id IN (...) query returns rows in whatever order the planner chooses, drops ids that don't exist, and never repeats a row for a duplicated key.

The fix is a small, fixed pattern:

  1. Run one query for all keys.
  2. Build a Map from each row's id to the row.
  3. Map over the original keys array, not the rows, and look each key up.

For a missing key, return null, or return an Error instance if absence is a failure.

What breaks when the contract is violated

A length mismatch is the easy case. DataLoader detects it and rejects every load in the batch with an error. An order mismatch is worse because DataLoader cannot detect it. If you return rows in database order, user 7's resolver can receive user 3's record, and nothing throws.

One-to-many and composite keys

For posts by authorId, group rows into a Map of arrays. Return one array per key, and use an empty array for authors with no posts. The result is an array of arrays that is still aligned to the keys.

When the key is an object such as { tenantId, id }, the default cache compares keys by reference. Two equal objects then miss each other. Supply a cacheKeyFn that serializes the key to a stable string.

Per-key errors vs. rejecting the batch

Placing an Error at one index rejects only that key's load(), so the sibling fields still resolve. Reject the whole batch only when the query itself failed.

import DataLoader from 'dataloader';

type User = { id: number; name: string };
type Post = { id: number; authorId: number; title: string };
type DocKey = { tenantId: string; id: number };
type Doc = DocKey & { body: string };
// Placeholder query helper (e.g. a thin wrapper over a Postgres pool).
declare const db: { query<T>(sql: string, params: unknown[]): Promise<T[]> };

// One-to-one: result[i] must belong to keys[i].
export const userLoader = new DataLoader<number, User | null>(async (ids) => {
  const rows = await db.query<User>('SELECT id, name FROM users WHERE id = ANY($1)', [ids]);
  const byId = new Map(rows.map((r) => [r.id, r] as const));
  // Iterate the keys, not the rows: restores order, fills gaps, repeats duplicates.
  return ids.map((id) => byId.get(id) ?? null);
});

// One-to-many: one array per key, empty array when an author has no posts.
export const postsByAuthor = new DataLoader<number, Post[]>(async (authorIds) => {
  const rows = await db.query<Post>(
    'SELECT id, author_id AS "authorId", title FROM posts WHERE author_id = ANY($1)', [authorIds]);
  const groups = new Map<number, Post[]>();
  for (const r of rows) groups.set(r.authorId, [...(groups.get(r.authorId) ?? []), r]);
  return authorIds.map((id) => groups.get(id) ?? []);
});

// Composite keys: serialize so two equal objects share one cache entry.
const docKey = (k: DocKey) => `${k.tenantId}:${k.id}`;
export const docLoader = new DataLoader<DocKey, Doc, string>(async (keys) => {
  // If this query throws, the promise rejects and every load() in the batch fails.
  const rows = await db.query<Doc>(
    'SELECT tenant_id AS "tenantId", id, body FROM docs WHERE (tenant_id, id) IN ' +
      '(SELECT * FROM unnest($1::text[], $2::int[]))',
    [keys.map((k) => k.tenantId), keys.map((k) => k.id)]);
  const byKey = new Map(rows.map((r) => [docKey(r), r] as const));
  // An Error at index i rejects only keys[i]'s load(); sibling fields still resolve.
  return keys.map((k) => byKey.get(docKey(k)) ?? new Error(`Doc ${docKey(k)} not found`));
}, { cacheKeyFn: docKey });
// In a real server, construct these loaders per request so caches never leak across users.

Three batch functions that keep results aligned to the input keys by mapping over the original keys array: a one-to-one lookup with null for missing ids, a one-to-many lookup returning an array of arrays, and a composite-key lookup that uses cacheKeyFn and per-key Error instances.

How do you scope DataLoader per request in Apollo Server?

Build a fresh set of loaders inside the Apollo Server context function, which runs once per incoming request. Return them on the context object, and have resolvers read them from the third resolver argument, for example context.loaders.userById. Resolvers should never import a loader directly.

The reason is the cache. A DataLoader instance memoizes every key it has loaded for its entire lifetime. If you create one at module level, it lives as long as the process does, and two problems follow:

  • Data leaks across users. User A's request fills the cache. User B's request then gets those cached values back without the batch function running again.
  • Authorization is skipped. Any permission check inside the batch function only ran for whoever triggered the first load. Later callers never reach it.

A per-request instance gives each request its own cache, and that cache is discarded when the response is sent.

Organizing loaders

Write one loader per access pattern, such as userById, postsByAuthorId, and orgBySlug. Keep them in a single loaders module that exports a factory, and have the context function call that factory. The factory can take the authenticated viewer as an argument, so the batch layer or the data layer below it can scope each query to what that viewer may see. Avoid enforcing authorization only in individual resolvers. Any other resolver that calls the same loader would bypass the check.

Keeping the cache correct

After a mutation, call clear(key) for each record you changed, or clearAll() when the change affects too many keys to list. If the mutation returns the updated record, call clear(key) and then prime(key, value). You need the clear first because prime does nothing when the key is already cached.

DataLoader does not cache a failure of the whole batch. It does cache a per-key Error. Before retrying a key that failed, call clear(key). Otherwise the retry immediately returns the same cached rejection.

import DataLoader from 'dataloader';
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { db, authenticate, typeDefs, type Viewer, type User } from './app';

// loaders.ts: one loader per access pattern, built by a factory for each request
export function createLoaders(viewer: Viewer) {
  return {
    userById: new DataLoader<string, User | null>(async (ids) => {
      // Authorization lives in the batch layer, so the query is scoped to this viewer
      const rows = await db.usersVisibleTo(viewer, ids);
      const byId = new Map(rows.map((u) => [u.id, u]));
      return ids.map((id) => byId.get(id) ?? null); // results must match key order
    }),
  };
}
type Context = { viewer: Viewer; loaders: ReturnType<typeof createLoaders> };

const resolvers = {
  Query: {
    // Read the loader from context and never import a module-level instance
    user: (_: unknown, { id }: { id: string }, ctx: Context) => ctx.loaders.userById.load(id),
  },
  Mutation: {
    renameUser: async (_: unknown, args: { id: string; name: string }, ctx: Context) => {
      const updated = await db.renameUser(ctx.viewer, args.id, args.name);
      // prime() does nothing if the key is already cached, so clear it first
      ctx.loaders.userById.clear(args.id).prime(args.id, updated);
      return updated;
    },
  },
};

const server = new ApolloServer<Context>({ typeDefs, resolvers });
await startStandaloneServer(server, {
  // Runs once per request, so each request gets its own empty cache
  context: async ({ req }) => {
    const viewer = await authenticate(req.headers.authorization);
    return { viewer, loaders: createLoaders(viewer) };
  },
});

A loaders factory takes the authenticated viewer and is called from the Apollo Server context function, which gives each request its own cache. A mutation clears the changed key and then primes it with the updated record.

How do you verify that DataLoader fixed the N+1 queries?

Start by measuring before you change anything. Wrap your database client in a thin counter that increments on every query and attaches the total to the request context, or turn on your driver's or ORM's query logging and group the log lines by a request ID. Run a nested list query, such as 50 posts each with an author, and record the count. Without batching you should see one query for the posts plus one per post. After adding DataLoader, the same request should issue one query for posts and one for authors. The count is the signal you care about, because it stays flat as the list grows, while the N+1 count grows with the data.

Then read the generated SQL. A working batch produces a single statement such as WHERE id IN (...) or WHERE id = ANY($1) with every distinct key in it. If you still see many single-key statements, a resolver is probably creating its own loader or calling the database directly.

Measurement shows the fix worked once. A test keeps it working. Write an integration test that runs the nested query against a seeded database through your real server setup. Have it read the counter and assert an exact query count, then seed more rows and assert that the count does not change. Exact assertions also catch a batch that has accidentally split in two.

This test is where most of the engineering time is saved. A later change can bypass the loader, for example a new field or a refactored resolver. When that happens, CI fails on the pull request with a clear number. Without the test, the regression stays hidden until real traffic and larger lists turn it into a latency incident that someone has to diagnose under pressure.

When should you avoid DataLoader, and what are the alternatives?

DataLoader only batches load() calls made in the same tick of the event loop. If a resolver awaits a permission check or a config lookup before calling load(), its keys arrive in a later tick and start a new batch. Ten such resolvers can still mean several queries instead of one. Move the await after the load(), or fetch the extra data through its own loader.

Large key sets cause a different problem. A single IN list with thousands of IDs can hit the database's bind-parameter limit or produce a slow plan. Setting maxBatchSize splits the keys into chunks, which costs more queries but keeps each one bounded. Choose the size from your database's limits, not from round-trip counts alone.

The per-request cache returns the memoized value even after a mutation in the same request changes the row. Call clear(key) or prime(key, value) after the write.

Per-parent pagination, such as the top 5 comments per post, does not fit a plain IN query. A single LIMIT applies to all parents together, so it cannot give each post its own five.

Alternative Use when Trade-off
SQL join in parent Child is always requested Over-fetches when the field is absent
Lookahead in parent resolver Selection set predicts the need Couples resolver to query shape
Window function (ROW_NUMBER() OVER (PARTITION BY ...)) Top-N per parent More complex SQL per field
Schema change (connection with explicit args) Access pattern is unbounded Client migration
Cross-request cache Hot, rarely changing data Needs its own invalidation design

What does DataLoader cost in development and operations?

DataLoader's costs fall mostly on the engineers who debug and test resolvers. Its benefits fall on the database and on consistency within a request.

Cost Why it happens Mitigation
Added indirection A resolver calls load() and gets a promise. The query itself runs later, in a batch function defined somewhere else. Keep one loader module per entity and name each batch function after its data source.
Harder stack traces An error thrown inside the batch function surfaces after the event-loop tick, detached from the field that requested the key. Include the keys in error messages and return per-key Error values instead of throwing for the whole batch.
Misleading per-field timing A field's measured duration includes time spent waiting for the batch to dispatch. That duration is not the cost of its own query. Treat field timings as wait time plus a share of the batch. Do not read them as query latency.
Tracing deferred execution The database span starts after the resolver spans that triggered it, and it belongs to none of them alone. Add a span around each batch function and record the key count and loader name on it.
Contract testing Same length, same order, and an error per missing key are not enforced by types. Unit-test every batch function with shuffled, duplicate, and missing keys.

The return on these costs comes in two forms. First, reads are consistent within a request: two fields asking for the same key get the same object, even if a write lands mid-request. Second, the pattern is reusable: once a loader exists, any new resolver that needs that entity gets batching without extra work.

Adopt DataLoader as the default if your schema exposes nested lists, many contributors write resolvers, or fields fan out to several backends. A plain join in the parent resolver is cheaper in some cases: a small schema owned by one team, a single SQL database, and a handful of fixed query shapes. That join is one query and one trace span, and anyone can read it.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to graphql dataloader n+1, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.