familienarchiv/docs/adr/022-eager-to-lazy-fetch-strategy.md

ADR-022 — EAGER→LAZY Fetch Strategy for Document Collections

Date: 2026-05-18 Status: Accepted Issue: #467 PR: #622

---

Context

A pre-production query audit of 24 HTTP requests to the document list and detail endpoints produced 2,733 SQL statements — primarily N+1 queries caused by FetchType.EAGER on Document.receivers, Document.tags, Document.trainingLabels, and Document.sender.

With EAGER fetch, every Document loaded by any repository method immediately triggers additional SELECT statements for each associated collection, regardless of whether the caller needs those associations. For a list of 100 documents, this means up to 400 extra queries for receivers alone.

---

Decision

Switch all four associations to FetchType.LAZY and use a two-tier strategy to load exactly what each code path needs:

Tier 1 — Named entity graphs on Document + @EntityGraph overrides on DocumentRepository:

• Document.full — loads sender, receivers, tags — used by findById (detail view)
• Document.list — loads sender, tags — used by findAll(Spec, Pageable), findAll(Spec), and findAll(Pageable) (list/search/dashboard paths)

Each repository method that is called from a hot code path has an @EntityGraph override that declares exactly which associations to JOIN-fetch, collapsing N+1 into 1–2 queries.

Tier 2 — @BatchSize(50) fallback on all four associations:

For any lazy access path not covered by an entity graph (e.g., a future ad-hoc query or an in-memory sort that touches trainingLabels), Hibernate batches the secondary SELECT to at most one statement per 50 entities instead of one per entity.

Session lifetime for post-return lazy access:

getDocumentById and getRecentActivity return entities to callers that may access lazy associations after the repository call returns. Both methods are annotated @Transactional(readOnly = true) to keep the Hibernate session open until the service method returns, making those post-return accesses safe.

This is an intentional exception to the project convention that read methods are not annotated (see CLAUDE.md §Services). The convention remains correct for all other read methods; this exception applies only to methods that serve lazy-initialized associations to their callers.

---

Alternatives Considered

@BatchSize-only (no entity graphs)

@BatchSize(50) on all associations would eliminate the worst N+1 cases (100 documents → 2 batch queries instead of 100 individual queries) without requiring repository overrides. Simpler to maintain — no named graph definitions, no per-method overrides.

Rejected because batch loading is best-effort: it depends on what Hibernate happens to find in the first-level cache and produces a variable number of statements. Entity graphs produce a deterministic, verifiable statement count that can be asserted in tests. The query-count test suite (DocumentRepositoryTest) validates the exact statement bounds on every CI run.

Single unified entity graph (Document.full everywhere)

Loading receivers on every list query is wasteful — the document list view only needs sender and tags. receivers is a @ManyToMany collection that, when JOIN-fetched together with tags, forces Hibernate to split into two queries anyway (to avoid Cartesian product). Using a single graph on list paths would load data the UI does not display.

Rejected in favour of two graphs with distinct scopes: Document.list for list paths (sender + tags), Document.full for detail paths (sender + receivers + tags).

@Transactional on the Spring Data repository methods

Spring Data allows @Transactional on repository interfaces directly. This would keep the session open for all calls to those methods without touching the service layer.

Rejected because the transaction boundary belongs at the service layer — repositories should not own transaction lifecycle. The service methods are the natural scope for "keep the session open long enough for the caller to use the result."

---

Consequences

• Query count reduced from ~2,733 to ≤10 statements per 24 HTTP requests — verified by DocumentRepositoryTest query-count assertions and DocumentLazyLoadingTest smoke tests.
• Read methods that return lazily-initialized entities must carry @Transactional(readOnly = true). Any future service method that loads a Document and returns it to a caller that accesses lazy associations must follow this pattern. Removing the annotation causes LazyInitializationException in production.
• New lazy code paths need an entity graph or @BatchSize review. Any new DocumentRepository method added to a hot code path should be assessed for N+1 risk and given an @EntityGraph override if warranted.
• @JsonIgnoreProperties({"hibernateLazyInitializer", "handler"}) required on serialized lazy-proxy entities. Person and Tag carry this annotation to prevent Jackson from attempting to serialize Hibernate proxy internals when the association is not initialized. Any new entity that is used as a lazy association and serialized directly (without a DTO) needs the same annotation.
• Named graph strings in Document.java and DocumentRepository.java must stay in sync. The @NamedEntityGraph(name = "Document.full") / @NamedEntityGraph(name = "Document.list") definitions on Document are referenced by string in every @EntityGraph(value = "...") on DocumentRepository. If the names diverge (e.g. a graph is renamed in one place but not the other), Spring Data throws at application startup. Always update both files together when renaming or restructuring a named graph.