GraphQL DataLoader: Fix Ordering, Missing Rows and Leaks

Why returning query rows directly is unsafe

A common first attempt sends all requested IDs to one query and returns the rows directly:

const userById = new DataLoader<string, User>(async (ids) => {
const { rows } = await db.query<User>(
'SELECT * FROM users WHERE id = ANY($1::uuid[])',
[ids],
);
return rows;
});

This looks fine because the SQL fetches the right set of users in one round trip. The trap is that "these rows were requested" is not the same as "these rows are in request order."

SQL returns a set of matching rows. The batch function has to produce an ordered array that matches the original key order - slot by slot.

A safer pattern is to map rows by their key and then walk the input keys:

function byKey<T, K>(
keys: readonly K[],
rows: readonly T[],
keyOf: (row: T) => K,
): (T | null)[] {
const map = new Map(rows.map((row) => [keyOf(row), row]));
return keys.map((key) => map.get(key) ?? null);
}

Now the returned array follows the input key sequence. And notice what else this preserves: one output slot per input key - even when a record doesn't exist. That "missing results" behavior matters just as much as ordering.

Treat the contract as correctness, not cleanup

When you review a loader, don't only ask, "Does it fetch the right rows?" Ask instead:

Can I prove that output position n matches input key n, including when a key has no row?

If your implementation maps by key and then iterates over the input keys, that proof is baked into the code. It's small, but it protects every resolver that uses the loader.

Why this can look correct in development

In small test databases, you can get lucky. If the inserted rows happen to line up with the order your test requests them, the query might coincidentally return rows in the same order. Your test passes - without ever proving the DataLoader mapping contract.

In production, that luck runs out. The query can still return valid user rows, but DataLoader will attach them to the wrong posts. One post that asked for u3 might get u1, and another might get u2. Nothing necessarily crashes. The response shape is still valid, and the names can look "reasonable," which makes the bug harder to notice than an obvious exception.

And adding ORDER BY in SQL usually isn't the right fix for this specific problem. Ordering by ID gives you "sorted by ID," not "sorted by the caller's input array order." You can write SQL that preserves the input order, but you still need to handle missing keys, and the ordering logic can get database-specific or harder to maintain.

Restore order in application code

A straightforward batch pattern looks like this:

1. Query all records matching the requested keys.
2. Index those records by the key field.
3. Build the output array by iterating over the original keys.

const userById = new DataLoader<string, User | null>(async (ids) => {
const { rows } = await db.query<User>(
'SELECT * FROM users WHERE id = ANY($1::uuid[])',
[ids],
);
return byKey(ids, rows, (row) => row.id);
});

This keeps correctness independent of whatever row order Postgres chooses, and it leaves the SQL focused on fetching matches rather than trying to satisfy a positional contract.

Do not let one missing record invalidate the batch

const userById = new DataLoader<string, User | null>(async (ids) => {
const { rows } = await db.query<User>(
'SELECT * FROM users WHERE id = ANY($1::uuid[])',
[ids],
);
return byKey(ids, rows, (row) => row.id);
});

Because the batch returns exactly one result per requested ID, a missing record becomes null in its own position. It won't shift later values or reject unrelated lookups.

What null means is a product and schema decision. If a missing author is expected, a nullable field may be fine. If the relationship "should always exist," your resolver can raise a clear error or your team can treat it as an integrity issue. The batch function's job is to preserve facts and ordering, not to invent policy for every caller.

Group rows for one-to-many relationships

Collections have a different shape. For a field like Order.items, you group rows by the parent key and return an array per requested parent. If an order has no items, it should get [] - not a missing result.

const itemsByOrderId = new DataLoader<string, OrderItem[]>(async (orderIds) => {
const { rows } = await db.query<OrderItem>(
'SELECT * FROM order_items WHERE order_id = ANY($1::uuid[]) ORDER BY created_at',
[orderIds],
);
const groups = new Map<string, OrderItem[]>();
for (const row of rows) {
const items = groups.get(row.order_id) ?? [];
items.push(row);
groups.set(row.order_id, items);
}
return orderIds.map((id) => groups.get(id) ?? []);
});

Here, ORDER BY created_at controls the order within each order's items. Meanwhile, orderIds.map(...) preserves the original batch key order (one output array per requested order). Treat those as separate concerns: SQL ordering helps with collection semantics, but you still need to map groups back to the requested keys.

Create loaders per request

A module-level loader lives for the lifetime of the process. If it caches a user fetched during one request, a later request can reuse it. That might mean stale data, or it might mean crossing a boundary where data shouldn't be shared.

Create loaders inside the function that builds your GraphQL request context:

context: () => ({
db,
loaders: createLoaders(db),
})

The framework hook varies, but the principle is consistent: share a loader among resolvers in the same request, not across unrelated requests. That gives you request-level deduplication without a process-wide cache quietly accumulating data.

Keep access policy aligned with cache identity

A loader keyed only by user ID stores one answer for that ID in its cache. If the batch result depends on who is asking (viewer permissions, tenant rules, roles), that cached value might not be reusable across access contexts.

You can handle this in a couple ways:

• Keep the loader request-scoped, fetch the record, and apply field-level access policy in the resolver.
• If the database query itself must enforce tenant-scoping, tie the loader (or its cache key) to that scope - don't assume a bare ID is enough to uniquely identify an authorization-safe result.

The underlying rule is simple: make your cache boundary line up with your data boundary. A per-request cache is not automatically safe if one request can include multiple viewers or access scopes. And moving authorization into the batch query is not automatically unsafe if your loader's key design includes the right scope. The right question is always: what does the cached value mean, who can reuse it, and for how long?

A practical DataLoader review checklist

Before shipping a loader, verify:

• The batch returns one result per input key, in input order.
• You map rows back to keys; you don't return query rows blindly.
• Missing singular records become null (or an explicit per-key error).
• Missing collections become [].
• Collection ordering is defined where the product needs it.
• Loaders are created per request, and cache scope matches authorization scope.
• Tests verify the relationship for each item, including non-insertion order and missing-row cases.
• Query-count tests stay, but they're treated as performance checks - not proof of correctness.

The key distinction is between an optimization test and a correctness test. You want both. The first makes sure the N+1 is gone; the second makes sure batching didn't change what the API means.