How do you return DataLoader batch results when the bulk lookup loses the key order?

## The failure this prevents You add a loader behind `OrderLine.menuItem`, the request count collapses from 1,137 to 1, the latency graph looks wonderful — and the response comes back half empty, with `menuItem: null` on hundreds of lines and, worse, a handful of lines showing the wrong item's name and price. Nothing errored. Nothing logged. The schema is unchanged. What broke is the alignment between the batch function's key list and the value list it returned. ## Why the rows come back scrambled A batch function is handed a list of keys and typically turns it into one bulk lookup — an `IN` list against a table, a multi-get against a key-value store, a bulk endpoint on an upstream service. **None of those preserve the order of the identifiers you sent.** A relational engine is free to return rows in whatever order its plan produces: index order, physical order, the order of a hash-join probe. A multi-get may return only the keys it found. An upstream bulk endpoint may sort by its own primary key, or return a map. Row order is an artefact of the plan, not a promise, and it can change when statistics change, when the table grows past a threshold, or when an index is added — which is why this bug is famous for shipping green and surfacing weeks later on a real data volume. Two distinct things therefore go wrong if you return rows as they arrived: * **Missing rows shorten the list.** Ask for 214 ids, get 211 rows because three items were archived, and every value from the first gap onward slides one position toward the front. Positions after the gap are wrong. * **Reordered rows misalign the list** even when the count matches. Every value can be present and every single one attached to the wrong key. The second is the dangerous one, because there is no null to notice. A line for a side salad renders the price of a steak. ## The one correct shape Build the result **by iterating the keys**, never by iterating the rows: 1. Run the bulk lookup with the key list. 2. Index the returned rows into a map from key to row. 3. Walk the original key list in order, emitting the mapped row for each key, or the appropriate empty value when the map has nothing. ```pseudocode function loadMenuItems(keys): rows = catalogue.findAllByIds(keys) byId = {} for r in rows: byId[r.id] = r return [ byId.get(k, null) for k in keys ] ``` The output list is now the same length as `keys` by construction, and each element sits at its key's index by construction. There is no ordering assumption left to be violated. ## What goes in an empty slot That depends on the field's type, not on the loader: * A **to-one** field (`OrderLine.menuItem`) gets `null` — and if the schema declared that field non-null, the null is a field error that propagates, which is a signal you want rather than a silent hole. * A **to-many** field (`Order.lines`) gets an **empty list**. Returning `null` for a key with no children makes "this order has no lines" indistinguishable from "something went wrong", and breaks a non-null list type. The mapping step also has to match the key type. If the key list holds strings and the rows carry integer ids, the map lookup misses for every key and the whole page comes back null — the same symptom for a different reason, and worth checking before you suspect the database. ## Sorting is not a fix A tempting shortcut is to sort the rows by id and return them. It fails on both counts: the key list is not sorted (it is in the order fields were resolved), and a missing row still shifts everything after it. Another is adding an explicit ordering clause to the bulk lookup that reproduces the key order. Some engines can do it, the syntax is dialect-specific, and it makes correctness depend on a query detail a future optimisation may rewrite. The map-and-map-back step costs one pass over a few hundred rows; on an 8,400-row page it is irrelevant next to the lookup itself. Pay it. ## How to catch it in tests A test with one key passes under every one of these bugs — one row cannot be out of order and cannot be missing without you noticing. Write the batch function's test with at least three keys, one of which has no matching row, and shuffle the rows the fake store returns. Assert on the returned list's length and on the value at each index, not merely on the set of values present. That is a five-line test that permanently closes the entire class of defect.