Skip to content

Embedded Aggregate Document

Denormalized document artifact — instantiates Access-Optimized Redundant Representation

Stores a whole entity and the related data it is always read with as one nested document, so a single-key fetch returns the entire aggregate with no joins or fan-out.

An Embedded Aggregate Document co-locates an entity and the child data it is almost always read alongside into a single nested document — one record that carries its own sub-lists inline rather than pointing at other tables. Where a normalized schema would spread an order across orders, line_items, addresses, and customers and reassemble them on every read, the embedded document keeps the whole aggregate as one JSON object addressable by a single key. Its defining decision is the aggregate boundary: what belongs inside the document because it is read, and often written, as a unit, versus what stays a reference because it lives its own life. Draw that boundary well and the dominant read becomes a single-key lookup; draw it wrong and you get either unbounded documents or the joins you were trying to escape.

Example

A support desk stores tickets in a document database. A ticket is almost never read alone — the agent view always needs the conversation thread, the customer's plan tier and contact, and the ticket's tags. In a relational store that is four joins on every page load. Instead the team embeds: one ticket document holds the status and subject, an inline messages array (author, body, timestamp), a small denormalized customer snapshot (name, plan, email), and a tags list.

Opening a ticket is now one read by ticket id — the entire agent view arrives in a single round trip, no joins, no fan-out to other collections. The boundary is drawn deliberately: messages and tags live inside because they are meaningless apart from the ticket and are written with it; the customer is referenced by id and snapshotted, because a customer outlives any one ticket and its full record must not be duplicated into thousands of documents. When the customer renames themselves, only the snapshot's few fields need refreshing — not the authoritative record, which stays in the customer service.

How it works

  • Draw the aggregate boundary. Decide what is read and mutated as one consistency unit (embed it) versus what is a long-lived, independently-owned entity (reference it, optionally snapshotting a few display fields). This boundary is the whole design.
  • Nest the owned children inline. Child collections that only exist within the parent become arrays inside the document, so retrieving the parent retrieves them for free.
  • Snapshot, do not absorb, references. For a referenced entity, copy only the handful of fields the read needs and keep the id; the source stays authoritative and the duplicated slice stays small and cheap to refresh.

Tuning parameters

  • Embed vs. reference threshold — how much related data lives inside the document. Embedding more makes the common read a single fetch but grows the document and duplicates data that must then be kept in sync.
  • Snapshot breadth — for referenced entities, how many fields to denormalize inline. Wider snapshots avoid follow-up lookups but widen the surface that can go stale.
  • Unbounded-array guard — whether an inline collection is capped or paged out. Letting a messages array grow without limit eventually pushes the document toward the store's size ceiling and slows every read of it.
  • Update granularity — whether the store can patch a single nested field or must rewrite the whole document. Coarse rewrites simplify code but amplify write cost on large documents.

When it helps, and when it misleads

Its strength is turning a multi-join read into one keyed fetch for data that genuinely travels together, and giving that unit a natural transactional boundary — the aggregate is written atomically as one document. It shines for read-mostly, self-contained entities: a ticket, a product page, an order.

It misleads exactly when the boundary is drawn for read convenience rather than true ownership. Embed data that is shared and every copy must be chased down on change, re-creating the write-time synchronization the design meant to avoid. Embed data that grows without bound and documents balloon toward the store's hard per-document size cap — real limits exist, such as a document database's 16 MB record ceiling — so an inline array that looked tidy at launch degrades every read years later. The honest guard is to embed only within a genuine aggregate[1] — a true consistency and ownership unit — and to reference-with-snapshot everything else, capping any collection that can grow unboundedly.

How it implements the components

Embedded Aggregate Document supplies the shape and read contract of a single self-contained record — not the freshness or repair machinery around it:

  • redundancy_scope_boundary — the aggregate boundary is the scope decision: precisely which related data is duplicated inside the document and which stays an external reference.
  • read_path_contract — it guarantees the dominant read a single-key, single-round-trip fetch that returns the whole aggregate with no joins or fan-out.
  • derivation_and_duplication_mapping — it defines which source fields are snapshotted inline from referenced entities, and the id kept back to the authority.

It does not detect or bound staleness of those snapshots (freshness_and_staleness_bound, divergence_signal) — that is Freshness Watermark — nor keep them current, which falls to a synchronization sibling such as Change-Data-Capture Propagation.

References

[1] In domain-driven design (Eric Evans), an aggregate is a cluster of objects treated as a single unit for data changes, with one root and a firm consistency boundary. Aligning the embedded document to a real aggregate — not merely to what is convenient to read together — is what keeps embedding from silently duplicating shared, independently-owned data. ↩