Why does a normalized client cache miss when a read selects a field it never stored?

## The read path is where normalization surprises people A document cache answers one question: have I seen this exact request before? A normalized store answers a harder one: can I *reconstruct* the answer to this request from objects I already hold? Reconstruction is a small execution engine running against local data, and it either completes or it does not. The algorithm is simple to state. Start at the root entry for the operation type. For each field in the selection set, look it up on the current entity. If the field's value is a reference, jump to that entity and recurse with the nested selection set. If it is a list of references, do that for each element. Assemble everything into the exact response shape the document describes. Now the failure case. Suppose the current entity has no key for a selected field. There is no value to place in the result, and the client will not silently omit the field, because the caller asked for a result matching the document. So the default policy is to abandon the read and fetch from the server. That is the *partial cache miss*, and it is the single most common source of "why is my client still hitting the network when the data is obviously right there?" ## Absent is not null The distinction that separates a middle answer from a junior one: a stored `null` is data. If a response returned `lastCountedAt: null` and the store wrote that, a later read of `lastCountedAt` is a hit yielding `null`. A field that never appeared in any response for that entity is not data — the store cannot tell whether it is null, a value, or an error, so it must ask. Candidates who conflate the two will predict hits where the client will actually refetch. ## A worked example in a warehouse inventory graph Two screens read the same pallets. The bin dashboard runs a list operation selecting `__typename`, `id`, `binCode` and `quantity` for the 34 pallets in bin `A-14-3`. After it resolves, the store holds 34 correctly keyed `Pallet` entries. The pallet detail screen then reads pallet `PLT-8842`, selecting those four fields plus `lastCountedAt`, `damageFlag` and a nested `Sku` with two fields of its own. The entity is present. Its key is right. Four of its selected fields are stored. The read still misses, on `lastCountedAt`, and the client issues a network request for the whole detail operation. The engineering response is not to "fix the cache" — the cache is behaving correctly. It is to make the overlap real: define the fields a `Pallet` needs on a named fragment and select that fragment from both operations, so the list write stores exactly what the detail read will ask for. That trades a fatter list response for a warm detail screen, and whether it is worth it depends on how often users drill in. ## Why clients default to all-or-nothing You might ask why the client does not return the four fields it has and fetch only the missing three. Some client libraries can be configured to return an incomplete result and let the caller decide, and a few can issue a narrowed follow-up operation. But the conservative default exists for good reasons: a caller that asked for a shape and received a different one has to handle undefined fields everywhere, and a per-field diff against the schema is real complexity for a benefit that a fragment discipline delivers more cheaply. Treat the strict default as correct behaviour to design around, not a defect to work around. ## The failure mode this produces in production The nastiest version of this is a schema change. Suppose a field is renamed — `quantity` becomes `unitCount` — and the change ships. Every entity already in every client's store carries the old field key, and nothing carries the new one. From the store's point of view, no entity has ever seen `unitCount`, so every read selecting it misses, and a client that had been serving screens locally starts fetching all of them. On the web that is a bad afternoon. For a released mobile client whose normalized store is persisted to disk across launches, it is worse: users restore a store full of entries that can never satisfy a read again, so the app pays full network cost on every screen *and* carries the dead entries until something evicts them. That is why a persisted client store is stamped with a schema or build version and dropped when the stamp changes — an empty store is strictly better than a store full of unusable entries. It is also why a rename is treated as a breaking change on the client side even when the server keeps both fields alive during a transition: the old clients keep working, but no released client's stored data survives the switch to the new name. ## What to say when asked how you would reduce misses Three levers, in order of cost. First, colocate field requirements in named fragments so that operations touching the same type genuinely select the same fields. Second, accept a slightly larger list payload where drill-in is the dominant navigation. Third, where a screen can usefully render before all its data arrives, split the operation so the cheap, already-cached part reads locally and the expensive part loads separately. What you should not offer is loosening completeness globally: you would trade a predictable network call for unpredictable undefined fields in view code.