What is the GraphQL N+1 problem and how do you detect it?

GraphQL resolves each field independently. Consider a schema where Query.posts returns [Post] and each Post has an author: User field. The naive resolvers are simple: posts runs SELECT * FROM posts LIMIT 50, and Post.author runs SELECT * FROM users WHERE id = ? using post.author_id. Each resolver is correct when you look at it alone. The problem appears only when they run together.

For a query requesting 50 posts with their authors, the executor calls the author resolver once per post. The database log shows one list query followed by 50 single-row lookups, often for the same handful of user IDs. That is N+1: one query for the list, plus N for the relationship. The cost grows with every additional nested list. If each author also resolves posts, the query count multiplies rather than adds.

Detecting it

Count queries per request, not per endpoint. Here are three ways to do that:

  • Enable statement logging in your database or ORM and tag each statement with a request ID.
  • Add tracing spans around data access. A flame graph that shows dozens of identical sibling spans under one GraphQL operation is the signature.
  • Assert query counts in integration tests.

DataLoader is a per-request batching and memoization layer that sits between resolvers and the data source. It collects individual load(id) calls and turns them into one bulk fetch. Teams running resolver-heavy APIs with list fields and relationships need it most.

// Naive resolvers for: type Query { posts: [Post] }  type Post { author: User }
// `db.query(sql, params)` is a placeholder for your database client.
const resolvers = {
  Query: {
    // One query for the list.
    posts: (_parent, _args, { db }) =>
      db.query('SELECT * FROM posts LIMIT 50'),
  },
  Post: {
    // Called once per post, so 50 posts means 50 more queries.
    author: (post, _args, { db }) =>
      db.query('SELECT * FROM users WHERE id = $1', [post.author_id])
        .then((rows) => rows[0]),
  },
};

// Query:  { posts { title author { name } } }
//
// Statement log for that single request (request ID req-7f3a):
// [req-7f3a] SELECT * FROM posts LIMIT 50
// [req-7f3a] SELECT * FROM users WHERE id = $1   -- [12]
// [req-7f3a] SELECT * FROM users WHERE id = $1   -- [7]
// [req-7f3a] SELECT * FROM users WHERE id = $1   -- [12]  (same user again)
// [req-7f3a] SELECT * FROM users WHERE id = $1   -- [3]
// ... 46 more single-row lookups ...
// Total: 51 statements = 1 list query + N (50) author queries.

module.exports = { resolvers };

Naive posts and author resolvers, with the statement log from one request showing one list query followed by a separate user lookup for every post, including repeated lookups for the same IDs.

Who should use DataLoader?

DataLoader fits any GraphQL server where a list field returns items whose child fields are resolved one at a time against a database or another service. In practice that means:

  • Teams with relationship-heavy schemas. If your types reference each other (posts to authors, orders to line items, users to teams) and clients can request those relationships inside lists, you will hit N+1 without batching.
  • Schemas maintained by several people or teams. When resolvers are written field by field by different contributors, nobody sees the combined query pattern. A shared set of loaders gives everyone the same batched path to the data.
  • Servers that wrap other services. If a resolver calls an internal HTTP or RPC service rather than a database, DataLoader works the same way, provided that service offers a bulk endpoint that accepts many IDs in one call. Without a bulk endpoint, the batch function has nothing to batch into, though per-request deduplication still helps.
  • APIs where clients choose query shape. Public or partner-facing GraphQL APIs cannot predict which nested fields will be requested, so per-field batching is safer than hand-tuning joins for each query shape.

It is less useful for schemas whose fields resolve single items at the root, for resolvers that already fetch complete nested data with a join, and for data sources that cannot fetch many keys at once. The section on when to avoid DataLoader covers those cases in more detail.

How does DataLoader work?

DataLoader combines three mechanisms, each of which is covered in detail in the sections that follow:

  1. Deferred collection of keys. A resolver calls loader.load(key) and immediately gets a promise. No fetch happens yet. The loader adds the key to a queue for the current batch.
  2. One batch function call per dispatch. At a scheduled point after the resolvers in the current execution step have run, DataLoader calls your batch function once with every queued key. Your function fetches all of them in one round trip and returns results in the same order as the keys. DataLoader then resolves each pending promise with its matching result.
  3. Memoization for the lifetime of the instance. Each loader remembers the promise it returned for every key. A second load() with the same key returns the same promise instead of fetching again. Because this cache lives as long as the loader instance, you create a new set of loaders for each request.

Resolvers therefore stay written as if they fetch one item, while the data source sees one bulk query per relationship per level of the query. The next section walks through how the batching step lines up with the GraphQL executor.

How does DataLoader batch load calls across resolvers?

When load(key) is called, DataLoader does not fetch anything. It records the key, returns a promise, and schedules a dispatch for later. In the JavaScript reference implementation, that dispatch runs after the current tick of the event loop finishes. Ports to other runtimes hook into an equivalent point, such as the end of an execution phase. Every key requested before the dispatch fires lands in the same queue and is passed to your batch function as one array.

This depends on how GraphQL executes a list field. When posts resolves to 50 items, the executor calls the author resolver for all 50 items before it awaits any of their results. Each resolver calls authorLoader.load(post.authorId) and gets back a pending promise. None of them blocks. By the time the executor yields, the queue holds all 50 keys. Duplicates are already collapsed.

  author(post1) ──load(7)──┐
  author(post2) ──load(3)──┤
  author(post3) ──load(7)──┼──▶ [ queue: 7, 3, 9 ] ──tick ends──▶ batchFn([7, 3, 9])
  author(post4) ──load(9)──┘                                          │
                                                                      ▼
                                                    SELECT ... WHERE id IN (7, 3, 9)
                                                                      │
  post1 ◀── user 7 ──┐                                                │
  post2 ◀── user 3 ──┼◀────────── results matched to keys ◀───────────┘
  post3 ◀── user 7 ──┤
  post4 ◀── user 9 ──┘

The resolver-to-query relationship is now many-to-one, and that changes debugging. A slow batch query appears as latency on every resolver waiting on it. Tracing spans for individual resolvers no longer map to a specific database call. To find the query responsible for a slow field, you need to trace or log at the batch function.

 GraphQL executor: posts resolves to [post1, post2, post3, post4]
 every author resolver runs before any result is awaited

 ┌───────────────┐
 │ author(post1) │──load(7)──┐     ┌─── DataLoader ──────────────────────┐
 ├───────────────┤           │     │ queue (keys deduplicated)           │
 │ author(post2) │──load(3)──┤     │ [ 7, 3, 9 ]                         │
 ├───────────────┤           ├────▶│ load() returns a pending promise    │
 │ author(post3) │──load(7)──┤     └──────────────────┬──────────────────┘
 ├───────────────┤           │                        │ tick ends: dispatch
 │ author(post4) │──load(9)──┘                        ▼
 └───────────────┘                 ┌─────────────────────────────────────┐
                                   │ batchFn([7, 3, 9]): one call        │
                                   └──────────────────┬──────────────────┘
                                                      ▼
                                   ┌─────────────────────────────────────┐
                                   │ Data source                         │
                                   │ SELECT ... WHERE id IN (7, 3, 9)    │
                                   └──────────────────┬──────────────────┘
                                                      │ rows
                                                      ▼
                                   ┌─────────────────────────────────────┐
                                   │ results matched to keys, in order   │
                                   │ [ user7, user3, user9 ]             │
                                   └──────────────────┬──────────────────┘
  post1 ◀── user 7 ──┐                                │
  post2 ◀── user 3 ──┤                                │
  post3 ◀── user 7 ──┼◀── promises resolve ───────────┘
  post4 ◀── user 9 ──┘

Four author resolvers call load() in the same tick. DataLoader removes the duplicate key 7, sends the remaining keys to one batch function and one query, then resolves each pending promise with the result matched to its key.

How do you write a correct DataLoader batch function?

The batch function receives an array of keys and must return a promise of an array with exactly the same length and order. Position i in the result belongs to key i. DataLoader trusts that alignment and does not inspect your rows to check it.

A correct implementation has three steps:

  1. Issue one query, SELECT ... FROM users WHERE id IN (...), using the deduplicated keys.
  2. Build a map from each row's id to the row.
  3. Return keys.map(key => map.get(key) ?? null).

You need the map because SQL does not guarantee that IN returns rows in key order, and it returns nothing at all for missing ids.

Returning the raw rows is the classic mistake. If one author was deleted, the array is too short, and DataLoader rejects the whole batch with an error. That case is loud. If every row exists but the database returns them in a different order, the array has the right length and nothing fails. Posts quietly render with the wrong author.

Watch for key type drift too. If the GraphQL layer passes "42" and the driver returns 42, every map lookup misses, and every field resolves to null without an error.

Testing the contract

The unit test should call the batch function directly with keys in a deliberately scrambled order. Include a duplicate key and an id that does not exist. Then assert three things:

  • The output length equals the input length.
  • Each element's id matches its key.
  • The missing key maps to null.

Capping batch size

A single request can collect thousands of keys. Very large IN lists can exceed the database's or driver's bind-parameter limit, and they can push the planner into a poor plan. Set DataLoader's maxBatchSize option, for example to a few hundred. DataLoader then splits the keys into several queries. You accept a few extra round trips in exchange for predictable query plans and no failures at parameter limits.

import DataLoader from 'dataloader';
import assert from 'node:assert/strict';

type User = { id: number; name: string };
type Db = { query(sql: string, params: number[]): Promise<User[]> };

export function makeBatchUsers(db: Db) {
  return async (keys: readonly number[]): Promise<(User | null)[]> => {
    const unique = [...new Set(keys)];
    // One query per batch. Postgres-style placeholders $1..$n.
    const placeholders = unique.map((_, i) => `$${i + 1}`).join(', ');
    const rows = await db.query(`SELECT id, name FROM users WHERE id IN (${placeholders})`, unique);
    // IN gives no order guarantee and omits missing ids, so index rows by id.
    // Number() guards against key type drift ("42" vs 42) from the driver.
    const byId = new Map(rows.map((r) => [Number(r.id), r]));
    // Same length and order as keys. Missing ids become null.
    return keys.map((k) => byId.get(k) ?? null);
  };
}

// Cap the IN list size. A large batch becomes several smaller queries.
export const makeUserLoader = (db: Db) =>
  new DataLoader(makeBatchUsers(db), { maxBatchSize: 200 });

// Test: the fake DB returns rows in reverse order and has no row for id 999.
const fakeDb: Db = {
  async query(_sql, params) {
    return params.filter((id) => id !== 999).reverse().map((id) => ({ id, name: `user${id}` }));
  },
};

const keys = [3, 1, 999, 2, 1]; // scrambled order, one missing id, one duplicate
const result = await makeBatchUsers(fakeDb)(keys);
assert.equal(result.length, keys.length);
result.forEach((u, i) => assert.equal(u?.id ?? null, keys[i] === 999 ? null : keys[i]));
assert.equal(result[2], null);

A DataLoader batch function that runs one IN query, maps rows back to key order with null for missing ids, and caps batch size, plus a test with scrambled, duplicate and missing keys that checks the length and order contract.

Why must DataLoader instances be scoped per request?

A DataLoader instance memoizes every key it has loaded for as long as the instance lives. That is fine for a single request and harmful for anything longer. Suppose one loader is created at module load and shared across the server. The first request for user 42 caches that row. Every later request for user 42 gets the cached object, including requests made after the row was updated. The cache never expires and grows with every distinct key. Sharing also mixes users. If one viewer's request caches a record, another viewer's request reads it back, whatever that second viewer is allowed to see.

The fix is to build loaders in the function that creates the request context. Most GraphQL servers call this function once per incoming operation. It creates a new set of loaders, such as userById and postsByAuthorId, and attaches them to the context object. Resolvers then call context.loaders.userById.load(id) and never import a loader directly. When the request finishes, the loaders and their caches become unreachable and are garbage collected.

Scoping by request does not cover authorization. A batch function that runs SELECT ... WHERE id IN (...) returns any row whose id it receives, so a resolver that skips its own permission check exposes data. Pass the viewer into the loader factory, as in createLoaders(viewer). Then enforce access in one of two places. You can put the condition in the batch query, for example by filtering on tenant or ownership. Or you can filter the results after loading and return null or an error for each row the viewer may not see.

This cache only removes duplicate loads within one operation. It is not an application cache. To share results across requests, add a separate cache with explicit expiry and invalidation behind the batch function.

import DataLoader from 'dataloader';
import { db } from './db'; // placeholder: db.query(sql, params) resolves to an array of rows
import { authenticate } from './auth'; // placeholder: resolves a token to a Viewer

type Viewer = { id: string; tenantId: string };
type User = { id: string; tenantId: string; name: string };

// Don't create loaders at module scope. Their cache would outlive the request
// and be shared by every user.
export function createLoaders(viewer: Viewer) {
  return {
    userById: new DataLoader<string, User | null>(async (ids) => {
      // The permission check lives in the batch query. Rows outside the viewer's
      // tenant are never fetched, even if a resolver skips its own check.
      const rows: User[] = await db.query(
        'SELECT id, tenant_id AS "tenantId", name FROM users WHERE id = ANY($1) AND tenant_id = $2',
        [ids, viewer.tenantId],
      );
      const byId = new Map(rows.map((r) => [r.id, r]));
      // DataLoader needs exactly one result per key, in key order.
      // A missing row or a forbidden row becomes null.
      return ids.map((id) => byId.get(id) ?? null);
    }),
  };
}

// Called once per incoming operation, whichever server framework you use.
// Fresh loaders mean a fresh cache that is garbage collected with the request.
export async function createContext(req: { headers: Record<string, string | undefined> }) {
  const viewer: Viewer = await authenticate(req.headers.authorization);
  return { viewer, loaders: createLoaders(viewer) };
}

type Ctx = Awaited<ReturnType<typeof createContext>>;

export const resolvers = {
  Post: {
    // Resolvers get loaders from context and never import a loader instance.
    author: (post: { authorId: string }, _args: unknown, ctx: Ctx) =>
      ctx.loaders.userById.load(post.authorId),
  },
};

A context factory builds a new, viewer-aware set of DataLoaders for each request and enforces tenant scoping in the batch query, and resolvers read the loaders from context.

Batching one-to-many relationships, arguments and the per-request cache

One-to-many loaders

A commentsByPostId loader receives post IDs and issues one query, such as WHERE post_id IN (...). The rows come back as a flat list, so the batch function groups them by post_id and then maps over the original keys. Each key gets an array of its comments. A post with no comments gets [], not undefined, because the result array must have exactly one entry per key and in the same order as the keys.

Arguments and cache keys

When a field accepts filters, a sort order or pagination, make those arguments part of the key. Use an object key with a cacheKeyFn that serializes it stably, so that {postId, sort} and {sort, postId} map to the same entry. Be careful with this. Each distinct argument combination is effectively a separate batch, so a loader with many parameters can end up issuing nearly one query per field again. Use a single loader only for keys that share the same arguments.

Using the per-request cache

Repeated keys in one request are loaded only once. When a list query has already returned full objects, call prime(id, obj) on the by-ID loader so later lookups skip the database. After a mutation, call clear(id) or prime the entry again with the new value. Otherwise, later reads in the same operation return the version from before the mutation.

Per-key errors

To report a failure for one key, put an Error in that key's position instead of throwing for the whole batch. Only that key's load() call rejects. GraphQL sets that field, or its nearest nullable parent, to null and adds an entry with a path to the errors array. The rest of the response still contains its data.

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

Verification needs a baseline. Pick one representative query, such as a feed of 50 posts with each post's author, and run it against the code before and after DataLoader. Keep the data set and the query the same. Then count the database round trips that request produces. You can get that number in two ways. You can turn on statement logging in the database and filter by a request ID. Or, if you already trace requests, you can count the database client spans that sit under the request's root span. The count is the main signal, and latency comes second.

Raw database spans tell you how many queries ran but not which resolver caused them. To fix that, add a span inside each batch function and tag it with the loader name and the number of keys. Every SQL query then nests under a loader span. A batch of size 1 that repeats 50 times shows a loader that is being bypassed or created inside the resolver.

Illustrative estimate, not a measurement: assume 2 ms per query. Without batching, the request makes 1 query for the posts and 50 for the authors. That is 51 round trips and about 102 ms of query time. With DataLoader it makes 2 round trips. The IN query over 50 keys will take longer than a single-row lookup, so expect the saving to be somewhat less than 98 ms.

Once you have the count, write it into a test. Run the query in CI and assert that it produces at most N database queries. An N+1 regression then shows up as a failing test with a clear number, rather than as a latency complaint that someone has to trace by hand weeks later.

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

DataLoader is not free. Every loader adds a scheduling delay while it waits to collect keys, a layer of indirection between the resolver and the query it triggers, and a batch function that needs its own contract tests. If a field only ever resolves one item, such as viewer or order(id:) at the root, there is nothing to batch. The same applies to a shallow schema whose lists never nest, where you pay that overhead and get no reduction in queries.

Batching also cannot collapse sequential dependencies. A loader can only batch keys it already knows. For users → posts → comments → author, the comment IDs do not exist until the posts batch returns. A deep query therefore still issues one batch per level, so its query count grows with depth even though it no longer grows with list size. To bound that, add depth limits, or use a purpose-built join for paths you know are hot.

Approach What it solves Development cost Main risk
DataLoader batching N+1 across sibling resolvers Low per loader Missing per-request scoping leaks data
Joins or lookahead in parent resolver Known deep paths in one query Medium to high Over-fetching, query-shape coupling
Denormalized or precomputed read models Expensive aggregates High Stale data, sync jobs
Shared application cache Repeated hot reads across requests Medium Invalidation bugs
Depth or complexity limits Unbounded or abusive queries Low Rejecting legitimate clients

Writing loaders and their contract tests takes some time up front. That cost pays back quickly in schemas that keep growing. Once userById or postsByAuthor exists, a new resolver reuses it instead of calling the database directly, so new fields are batched by default rather than reintroducing N+1 patterns later.

How can DataLoader save engineering time?

The main saving is not query latency. It is the time engineers would otherwise spend finding, fixing and re-fixing query patterns by hand.

  • Resolvers stay simple. Without batching, the usual fix for N+1 is to make a parent resolver look ahead at the requested fields and build a join for that query shape. That code is hard to review and breaks when clients change their queries. With a loader, each resolver is still a one-line load(id) call, and the batching is handled in one place.
  • One fix covers every caller. A relationship fetched through userById is batched wherever it appears in the schema: post authors, comment authors, team members. You write and test the batch function once instead of optimizing each field separately.
  • Fewer production investigations. N+1 problems usually surface as slow requests under real data volumes, and tracing them means reading statement logs and matching queries to resolvers. A query-count assertion in CI and loader-level tracing spans turn that into a failing test or a clearly labelled span, which takes far less time to diagnose.
  • Authorization lives in a predictable place. When tenant or ownership filtering sits in the loader factory, reviewers check one batch query rather than auditing every resolver that touches the same table. New resolvers inherit the check by using the loader.
  • Onboarding is faster. A convention of "fetch related data through context.loaders" is easy to explain and easy to spot in code review. New contributors do not need to understand the full query plan of the schema to add a field safely.

The cost on the other side is the upfront work of writing loaders, their contract tests and the per-request context wiring. That work is small for each loader and is reused by every field that follows, which is why the time saved tends to grow as the schema grows.

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.
  • Changing a route's URL or method automatically notifies the services that consume it — no hunting through repos for callers.

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.
  • Consumers learn about a breaking change at review time rather than from production errors.
  • 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.