A data-access interface hides how its results are fetched. Which fetching decisions can it hide from callers, and which cannot?

## What a boundary genuinely hides A data-access interface exists partly to keep query mechanics out of its callers, and it does that well. Behind a named method the layer is free to change: - the **statement text** and the join strategy used to assemble the result; - **which columns** are read, and whether a value is computed in the database or afterwards; - whether an index, a materialised structure or a shared cache answered part of the request; - how **keys are generated** and how results are mapped onto objects; - whether a filter is one predicate or several, as long as the result set is the same. None of that is observable from the call site, and all of it can be improved without touching a single caller. That is the real payoff of the boundary, and it is worth defending. ## What escapes anyway What the boundary cannot hide is the **cost and the timing** of the fetch, because the caller experiences both. 1. **How many statements the call runs.** A method that looks like one lookup may run one statement per row of a collection it walked. The caller sees it as latency, the database sees it as load, and no amount of naming hides it. 2. **What was loaded and what was left out.** If part of the graph is unloaded, the caller finds out by touching it: either another query runs, or - outside the scope that owned the object - the read cannot be satisfied at all. Whether the caller must avoid touching that part is a fact about the returned value, so it belongs in the contract. 3. **Whether the result is tracked.** A caller that mutates a tracked object writes to the database; a caller that mutates a snapshot writes nothing. Same-looking code, opposite outcome. 4. **Volume.** A method that returns everything matching a filter has handed the caller a memory profile that depends on data, not on code. 5. **Ordering and paging stability.** A page defined by an offset over an unstable ordering skips and repeats rows under concurrent writes. Callers build on the ordering whether or not the contract mentions it. 6. **Transaction and lock scope.** Streaming a large result keeps a scope, and often a snapshot or locks, alive for as long as the caller takes to consume it. The caller controls that duration. | Decision behind the boundary | Hideable? | How it reaches the caller | |---|---|---| | Statement text and join strategy | Yes | Not observable | | Which index or cache answered | Yes | Not observable | | Number of statements per call | No | Latency and database load | | Loaded versus deferred parts | No | Later query, or a failed read | | Tracked versus snapshot result | No | Whether a mutation is written | | Result volume | No | Memory, and time to first use | | Ordering and paging stability | No | Skipped or repeated rows | | How long a scope stays open | No | Lock and connection hold time | ## The rule this leads to A boundary can hide the **mechanism** and not the **cost**. So the contract has to state the cost - not in prose nobody reads, but in the shape of the interface: 1. **Name what comes back loaded.** A method whose result is safe to walk in full is a different method from one whose result is a stub, and they should not share a name. 2. **Make the tracked-versus-snapshot distinction visible in the return type**, so a caller can see whether mutating the result means anything. 3. **Separate the streamed or unbounded read.** A method that requires an open scope and consumes as it goes should say so, because the caller now owns the duration. 4. **Pin the ordering** of anything paginated, on a key that does not move. 5. **Assert the statement count** of important call paths in an automated test. Prose about how many queries a method runs decays; an assertion fails on the commit that changed it. ## Why "add another method" is not always the fix When a caller needs a differently-fetched result, the tempting move is a second method with a longer name, and then a third. That is often right - it keeps the fetch decision inside the layer, where it can be seen and changed. It stops being right when the methods multiply because callers are really composing arbitrary filters through the boundary; at that point the interface is a query language with an awkward syntax, and the honest options are a named read boundary per use case or an explicit query type. Layers also differ in how much of this is even negotiable: some resolve unloaded parts on access, which turns a fetch decision into a latency surprise, while others require every part to be requested up front and fail loudly instead. The first hides more and leaks later; the second hides less and leaks immediately. Knowing which behaviour a layer has tells you how much the contract has to say out loud - and neither behaviour lets the boundary claim that fetching is somebody else's problem.