Document Data Modeling

Embed when the related data is bounded in size, read with its parent, and changes with it. Reference when it is unbounded, shared by many parents, edited independently, or queried on its own.

It means the database does not check a document's shape when you write it — not that there is no schema. The schema still exists, implicitly, in the code that writes and reads documents. Enforcement moved; it did not disappear.

A write to one document lands entirely or not at all, so one document is the widest scope where an invariant can be enforced for free. Any rule that must always hold should sit inside a single aggregate; rules spanning documents need extra machinery or must tolerate lag.

Query-first modelling starts from the list of operations the application must serve and shapes documents so each one is answered by a simple, well-targeted access. The document shape follows the workload, not a diagram of entities.

Fan-out on write copies a fact into every document that will need it at write time, so reads are single lookups. Fan-out on read stores it once and gathers it from many sources per read. Choose by read-to-write ratio and fan-out size.

An array with no ceiling eventually pushes the document past the store's hard size limit, and long before that every read and every update of the parent pays for the whole array. Move those children into their own records.

It records which shape generation a document was written with. With no ALTER TABLE, one collection holds several generations at once, so the stored version lets read code branch deterministically instead of inferring shape from which fields happen to be present.

Lazy migration converts a document when application code touches it, so cold records never convert and branch code lives forever. A backfill sweeps the whole collection and gives a finish line. Most real migrations ship the tolerant reader first, then backfill, then delete the branch.

Enforce the coarse contract in the database — required fields, types, allowed discriminator values — because it catches every writer including scripts and migrations. Enforce semantics and cross-field business rules in application code. Use both layers; they cover different failure modes.

An aggregate is the clump of data you load, write and keep consistent as one unit. A document is an aggregate when its contents are always used together and nothing outside it must change atomically with it.

The price paid is a distinct historical fact the order owns, so it must never track the product's current price. A copied product name is a cache of a mutable fact elsewhere and carries a synchronisation obligation. Only the second is duplication debt.

A write to one document is atomic; a write spanning two is not. Once related data is referenced, an update can be observed or left half-applied, unless you pay for a multi-document transaction or design the drift away.

Treat an absent version field as the oldest known generation by convention, rather than rewriting every document just to stamp a number on it. Read code normalizes missing to 1, and migration progress is counted as documents that are missing the field or below the current generation.

Absent usually means the fact was never recorded or does not apply; explicit null means it was recorded as deliberately empty. Document stores distinguish the two, so pick one convention per field and apply it everywhere rather than letting both appear.

Keep different shapes together when they are read by the same queries, share a common core of fields, and need the same indexes. Split them when access patterns, growth rates or retention differ. Always carry an explicit type field to tell variants apart.

Crossing an aggregate boundary costs an extra access the application must issue and order, no automatic all-or-nothing across the two, and no engine-enforced referential integrity. The usual failures are N+1 read patterns and half-finished multi-document writes.

Measure both paths, then let the dominant one own the primary aggregate and serve the other from a derived shape or extra accesses. Boundaries protect invariants first; beyond that, the heavier and more latency-sensitive path wins.

Increment it atomically within its own document, make the increment idempotent so retries cannot double-count, store a marker of what has been counted, and run a periodic recompute from the source that detects and repairs drift instead of assuming none.

Classify each duplicated field by what a wrong read costs: display-only fields tolerate seconds or minutes, while money, permissions and inventory tolerate nothing and must be read from the source. Then pick a propagation mechanism whose measured lag meets that bound, and add a sweep that caps the worst case.

Put the array on the side whose list is genuinely bounded, and never on a side that can grow without limit. When both sides are unbounded, or the relationship carries its own attributes, give it a collection of link documents.

Copy a field next to its reference when the hot read needs only that field and resolving the whole referenced document would cost an extra round trip. Prefer fields that are immutable or that record a point-in-time value.

The previous release must still be able to read documents the new release wrote. That means shipping the tolerant reader before the new writer, keeping the old fields populated while both releases can run, and delaying any destructive rewrite until rollback is off the table.

A tolerant reader takes only the fields it needs, ignores everything it does not recognise, and treats a missing field as a defined default. That makes additive changes by writers safe, so producers can evolve without coordinating a release with every consumer.

Anchor the boundaries on what is stable — the invariants and the units the business writes as a whole — keep aggregates modestly sized, avoid unbounded nesting, and treat everything derived as replaceable so shapes can change as real access patterns appear.

Measure what the duplication actually buys on the read path, then count the maintenance surface: how many writers can create these documents, how often the field changes, and whether the copies are even findable. Keep duplication only where the read win survives an honest edit and repair cost.

Measure how many documents sit on each generation, price each surviving branch as permanent code and test surface, then set a supported-generations floor. Fund a backfill to clear everything below it, verify a zero count including consumers outside your service, and enforce the floor with monitoring so the count cannot creep back up.

Give each collection a single owning team that publishes its core contract, allow additive change freely, gate anything non-additive, back the contract with a narrow write-time check, and measure real drift by sampling stored documents rather than trusting the code.