Loading Strategies

The join returns one row per matching child, with the parent's columns repeated on every one of them. A layer that produces one result entry per row therefore hands back the same parent once per child row.

Eager means the linked data is loaded as part of the read that returns its owner - in the same statement through a join, or in an immediate follow-up statement - so nothing has to load later when code touches the link.

Any access that needs data the row has not supplied fires the load: reading a mapped field, iterating or sizing a collection, or calling a behaviour method on the stand-in. Reading the identifier it already holds does not.

The read fails at that moment. A deferred link still needs its own query to fill itself, and the unit of work and connection that would run it are gone, so most layers raise an error instead of returning data.

The layer issues one extra statement per deferred collection, reading children whose owner key comes from a subquery repeating the driving query's predicate. Statement count stops depending on how many owners returned, but that predicate is evaluated twice.

A mapping-level eager declaration is global: every read of the owner pays it, including loads the layer issues itself. A per-query fetch is local to one use case. Queries can usually widen a deferred link, but rarely narrow an eager one.

A stand-in is an instance of a type the layer generated, not of the mapped class. Exact-class tests fail, casts to a concrete subtype fail even after loading, and equality over runtime classes is asymmetric.

A stand-in faults in by making the caller wait, and a non-blocking layer has nowhere to wait. So a plain accessor cannot load: links are named in the query, exposed as a deferred handle, or fetched by a second call.

Four sites dominate: output serialisation, view rendering, async or queued work, and an object held past its request in a cache or field. All escape review because a deferred read looks like a plain field access, with no query at the call site.

A row limit counts grid rows, and a row is one parent-child pair, so ten rows may be two parents with a collection cut off mid-way. Page the parent keys first, then fetch those parents with their collection.

Decide the shape at the read: project to a transfer model for read-only output, or name the links the use case needs when loading the root. Below those, initialise explicitly before the object leaves. Keeping the unit of work open ranks last.

The layer takes keys from unfilled stand-ins of the same kind in the current unit of work, up to a configured maximum, and emits one set-membership statement. Leftover keys form a shorter final list, sent as-is, rounded, or padded.

De-duplication happens in memory, after the rows are assembled: entries sharing a parent key collapse to one. A SQL DISTINCT cannot do it because the rows differ in their child columns, so it removes nothing and adds a sort.

The two collections are crossed: each parent yields the product of the two child counts in rows, so four of one and three of the other give twelve rows. Each collection's contents are multiplied by the other's size.

A named fetch plan is a reusable, named description of which links a read should materialise, declared once and attached to a call. It beats inline fetches when several call sites share one shape, or when the read has no query text - a load by identifier.

The layer needs a collection it controls: one recording whether the rows were read, which object owns it, and what was added or removed. On load it installs its own implementation, discarding the constructor's instance.

The call returns before any statement runs: work starts when the caller consumes, rows arrive one by one, and errors can surface mid-sequence. The connection stays checked out for the whole consumption, so a slow consumer holds it.

A joined fetch buys one round trip and pays by repeating every owner column once per child row. Batched secondary statements send each row once, keeping bytes near owners plus children, and pay in extra round trips.

Counting over a fanned-out grid counts parent-child pairs, so the total is inflated and the page count is wrong. Count parents: drop the collection joins, or count distinct parent keys when a filter forces the join to stay.

Over-fetching costs bytes, not round trips: wide rows, whole graphs and unbounded collections pulled for a screen that shows a fraction. A statement counter stays flat while transfer, hydration and heap grow, so the budget never trips.

Ask the layer, not the object: a load-state predicate reports whether a link or one attribute has been fetched, without touching it. Use it in generic code that walks object graphs and cannot know the caller's fetch plan.

A blocking layer keeps the current unit of work in thread-bound storage. Non-blocking work resumes on other threads, so that slot is empty or holds another request's context, and the statement quietly runs on its own connection.

A mapped object was used as a message. Its unit of work ended with the request, so the deferred link has no loader and the filled fields are a stale snapshot. Send identifiers instead, and let the job read in its own unit of work.

Set it per access path, anchored to the page size that path returns, keeping the service to a few recurring sizes. Justify it with statements per request, rows fetched against rows touched, and tail latency before and after.

Push fetch decisions out of the mapping and into per-use-case plans, keep large values out of the rows that every read touches, cap what a collection fetch may return, and enforce a volume budget in tests - not only a statement count.

Pick where the system pays: at design time, letting only fully materialised boundary types leave a transaction, or at runtime, keeping units of work open and absorbing implicit queries. The first costs mapping work; the second costs latency nobody sees.

A link is reached only through a reference, so the layer can put a stand-in there. A deferred column is a field of the object you already hold, so the class's own field reads must be instrumented instead.

The pool bounds database concurrency either way, so a non-blocking layer buys no extra throughput. It buys threads: waiting requests stop occupying them, so overload queues instead of exhausting a thread pool. It costs explicit fetching and manual context.