Batch function contracts: ordering, shapes, errors

Sven wires DataLoader and the page is fast — for most requests. Occasionally posts show the wrong author. The SQL query ran correctly and returned the right rows. The bug is in the batch function: it returned rows in the order Postgres chose, not the order DataLoader expected.

The ordering contract

batchLoadFn(keys: Array<K>): Promise<Array<V | Error>> must return an array of the same length as keys, with values at matching positions. If keys = [7, 9, 3] then the return must be [row7, row9, row3] — in that order.

Postgres (and most databases) do not guarantee row order from a WHERE id IN (...) query. If the query returns [row9, row7, row3], and you return that array directly, DataLoader resolves:

• key 7 → row9 (wrong)
• key 9 → row7 (wrong)
• key 3 → row3 (correct by coincidence)

This is a silent bug: no error is thrown, tests may pass, and production serves wrong authors on intermittent queries.

The fix: build a Map from the results, then walk the input keys.

async function batchAuthors(ids) {
  const rows = await db.query(
    'SELECT id, name FROM users WHERE id = ANY($1)', [ids]
  );
  const map = new Map(rows.map(r => [r.id, r]));
  // Walk ids in input order; return null for missing rows
  return ids.map(id => map.get(id) ?? null);
}

Handling missing rows

If a key has no matching row in the database, map.get(id) returns undefined. Returning undefined in a slot resolves the Promise to undefined, which propagates to the resolver as the field value. For non-nullable GraphQL fields this causes a validation error at runtime.

The correct approach depends on the field’s nullability:

• Nullable field: return null for missing rows.
• Non-nullable field that should always exist: return new Error('User not found: ' + id).

Returning an Error in a slot causes DataLoader to reject only that specific .load() Promise, not all pending loads. This is the opposite of throwing from the batch function, which rejects all pending Promises.

One-to-many shape

For a field like Post.tags, the loader key is the post ID and the value is an array of tags. Empty arrays are mandatory for posts with no tags — if you return undefined or skip the slot, the next post’s tags fill in.

async function batchTags(postIds) {
  const rows = await db.query(
    'SELECT post_id, tag FROM tags WHERE post_id = ANY($1)', [postIds]
  );
  // Pre-fill every key with an empty array
  const map = new Map(postIds.map(id => [id, []]));
  rows.forEach(r => map.get(r.post_id).push(r.tag));
  return postIds.map(id => map.get(id));
}

Count shape

For Post.likeCount, the batch runs GROUP BY post_id COUNT(*) and maps back to a count (defaulting to 0 for posts with no likes).

maxBatchSize

When a single GraphQL document references 5000 unique authors, a single WHERE id IN (...) with 5000 IDs is slower than five queries of 1000 due to Postgres planner overhead. Set options.maxBatchSize (typical: 500–1000) to split large batches automatically.