We already know what NoSQL is, why it exists and how each of its four families is operated. And yet, with all of that, we still do not know how to do the most important thing: design well.

This is the lesson where most projects go wrong. MongoDB's syntax is learned in an afternoon; document modeling is where it is decided whether the system will still be fine in two years or whether it will have to be rewritten. And the trap is that a bad design works perfectly on day one: with 200 documents everything is fast and nothing fails. The damage appears when the collection grows, when a document approaches its size limit or when somebody discovers that a branch name is duplicated across 40,000 documents and has just changed.

We are going to invert the mental order we learned in module 2, define precisely what an aggregate is, settle the most important decision in document modeling —embed or reference— with explicit criteria instead of intuition, learn the five design patterns that solve almost every real case and the four anti-patterns that spoil them, and recover part of the lost guarantees with schema validation.

The deliverable at the end is concrete: the definitive design of BiblioRed's three collections —reviews, catalog and activity— with example documents and the justification for every decision.

1. The change of mindset: from the domain to the queries
2. The aggregate: unit of reading, writing and atomicity
3. The central decision: embed or reference
4. One-to-few, one-to-many, one-to-squillions
5. Controlled duplication and how to keep it consistent
6. Pattern: extended reference
7. Pattern: subset
8. Pattern: bucket
9. Pattern: outlier
10. Pattern: computed field
11. Anti-patterns you have to recognize
12. Schema validation with $jsonSchema
13. Document versioning and schema evolution
14. Indexes, briefly
15. Deliverable: the final design of BiblioRed's collections
16. Common mistakes and tips
17. Exercises
18. Conclusion

In module 2 we followed, without naming it, a very specific method:

1. Identify the entities of the domain: branches, members, books, copies, loans.
2. Give each one its table, with its keys and its relationships.
3. Normalize to eliminate redundancy (we will formalize this in module 5).
4. And afterwards write the queries, confident that the model will withstand any question.

That last point is the great virtue of the relational model: a well-normalized schema answers questions nobody had foreseen. The design is independent of the use.

In NoSQL the order is inverted:

1. List the queries the application needs to serve, with their frequency and their latency requirement.
2. Design the documents so that every frequent query is resolved in a single access.
3. Accept whatever duplication is needed to achieve that.
4. And afterwards check that the domain entities are still recognizable.

This has an uncomfortable consequence that is best accepted early: the same domain admits completely different document designs depending on how it is queried. There is no such thing as "the correct model of a library" in MongoDB; there is the correct model for BiblioRed's portal with these queries. If the usage changes radically tomorrow, the model can become obsolete even though the domain has not changed.

That is why the first step of document modeling is not drawing entities, it is writing the list of queries. BiblioRed's, prioritized:

Everything that follows is the answer to this table.

We introduced the concept in lesson 03-01. Now we make it precise, because it is the main working tool.

An aggregate is a set of data that meets all three conditions at once:

1. It is read together: the application almost never needs one part without the others.
2. It is written together: changes affect the set coherently.
3. It has a root: a main entity that gives the set its identity and through which it is accessed.

And from there comes the property that governs the whole design:

The aggregate is the boundary of atomicity. In MongoDB, writing a document is atomic: either it is applied in full or it is not applied at all. Everything inside the document is updated in one piece, with no transaction. Everything outside needs an explicit transaction or it will be exposed to temporary inconsistencies.

That sentence is the most useful design criterion you take away from this lesson. When you hesitate between putting something inside or outside, ask yourself: do I need this to change atomically together with the rest? If the answer is yes, inside.

An example at BiblioRed. A review with its text, its score, its tags and its vote count is an aggregate: when a reader edits their review, the text and the tags change at the same time, and nobody should see the new text with the old tags. The review and the material's record, on the other hand, do not form an aggregate: the record is edited from the librarian's panel, the review from the public portal, at different rhythms and by different people.

The whole practice of document modeling comes down to this question: when two entities are related, does the child go inside the parent's document or into its own collection with a reference?

Do not decide by intuition. Go through these six criteria in order:

Criterion 5 deserves a special warning, because it is the one that has broken the most systems: anything that grows over time with no cap ends up being a problem if it is embedded. The reviews of a popular book, activity events, the messages of a chat, the loan history. Even if there are three today, in five years there will be thousands. And there is a cost you do not see coming: MongoDB, when updating a document that has grown, may have to rewrite it whole on disk. An 8 MB document to which a 200-byte element is added costs 8 MB to rewrite.

If the child makes no sense without the parent and disappears with it, it almost always goes embedded. An address without its member means nothing: inside. A review, on the other hand, has an identity of its own —it is linked, voted on, reported, it appears on its author's profile—: outside.

The fastest way to apply the six criteria is to classify the relationship by its cardinality. It is the most quoted rule of thumb in document modeling and it works surprisingly well.

The difference between the last two rows is subtle and crucial. In one-to-many, the parent can keep the list of its children's identifiers, because it fits. In one-to-squillions, that list would be an array of 40,000 elements growing every day: the link must go only in the child, pointing upwards.

Applied to BiblioRed, case by case:

Material and tags → embed. A material has between three and eight tags, they do not grow out of control, they are always displayed with the record and they are not queried separately (search by tag is resolved with an index over the embedded array, not with another collection). All six criteria point to embedding.

Material and reviews → reference, with a subset. Reviews grow without a cap, they are queried separately (member profile, moderation), they change often (helpful votes, edits, replies) and they are the main entity of query C2. They go into their own collection. But query C1 —the most frequent in the system— wants the record with its best reviews in a single access, so the material's document also keeps a copy of the top five. This is the subset pattern of section 7.

Material and copies → neither one nor the other. The physical copies, with their status and their branch, stay in PostgreSQL. They are intimately tied to loans, which are transactional. MongoDB's catalog keeps only a denormalized availability counter so it can render "3 available at Central" without querying the other database. Recognizing that a piece of data must not migrate is a modeling decision too.

Member and activity → one-to-squillions. Each event is a document (or better, an element inside a bucket document, section 8) pointing at the member. The member's document keeps no list of events.

In module 2 redundancy was the enemy. In document modeling it is a tool. But it is a sharp tool, and you have to hold it by the handle.

Duplication is justified when the cost of maintaining it is lower than the cost of rebuilding the data on every read. And that calculation almost always depends on a single question: how often does the duplicated data change, compared with how often it is read?

There are three categories of duplicated data, and they are treated differently:

It never changes, so duplicating it is free.

A book's ISBN and its year of publication are fixed. Copy them without remorse.

Here duplication is not an optimization: it is semantic correctness.

If Marta changes her surname in 2027, do her 34 reviews have to be rewritten? It depends on what the field represents:

• If it is "the name shown now", yes: it has to be propagated.
• If it is "who signed this in March 2026", no: it is a historical fact and rewriting it would be falsifying it.

It is the same distinction as on an invoice: the price of the product at the moment of sale is copied into the invoice line and never touched again, even though the catalog changes tomorrow. Explicitly deciding which category each duplicated field falls into —and writing it in the project documentation— avoids arguments and errors later on.

These are the dangerous ones. A material's title appears in its reviews; if the librarian corrects it, there are reviews with the old title.

Three strategies, with their cost:

And here the price of NoSQL we announced in 03-01 appears in all its rawness: those two operations are not atomic with respect to each other. If the process goes down between the first and the second, the catalog has the new title and 47 reviews have the old one. In PostgreSQL this problem would simply not exist, because the title would be in a single place.

The available defenses: wrapping both writes in a MongoDB transaction (possible since 2018, with a performance cost), or —more commonly— designing the system so that the temporary lag is tolerable and scheduling a periodic reconciliation process that detects and corrects the divergences.

Golden rule: duplicate only what is displayed, never what is used to decide. Duplicating a material's title to render it in a list is reasonable. Duplicating its price or its availability status to make a business decision based on the copy is not.

Problem. Referencing is correct, but it forces a second query in order to display four fields from the referenced document.

Solution. Alongside the reference, copy the few fields the view needs. Not all of them and not none of them: the ones that get rendered.

Field selection criterion: copy what is stable and displayed. The title and the type are stable; the cover changes rarely. Do not copy the synopsis (long and editable) or the number of available copies (it changes with every loan). That is what the reference is for.

When to apply it: it is the most used and most useful pattern in document modeling. Any list showing elements from two collections is a candidate.

Problem. The material's document could contain all of its reviews, but a popular title has 800 and the record only shows the best five. Embedding 800 documents in order to render five means loading 160 times more data than necessary in the system's most frequent query.

Solution. Keep in the parent a copy of the subset the view needs, and the complete set in its own collection.

With that, query C1 —the full record, the most frequent in the portal— is a single findOne. Anyone clicking "see all 812 reviews" will make a second query against reviews, but only a fraction of visitors do that.

How the subset is maintained. Every time a review gains votes, a check is made on whether it should enter the featured list:

This recomputation does not have to be immediate: it can run every few minutes in the background. Nobody minds a review taking ten minutes to appear in the featured list, and in exchange you avoid running the recomputation on every single vote.

When to apply it: whenever the main view needs only the first N of a large collection.

Problem. The activity log generates 17 million events a year. One document per event means 17 million tiny documents, each with the overhead of its _id, its index entry and its internal metadata. In many cases, the overhead weighs more than the data.

Solution. Group the events of the same entity and the same period into a single container document.

Inserting an event becomes a single operation that creates the container if it does not exist and adds the event if it does:

upsert: true is the key: if the day's document does not exist, it is created; if it exists, it is updated. $setOnInsert sets the fixed fields only on creation, so they are not rewritten every time.

The numbers behind the change, with BiblioRed's estimates:

How to choose the container size. Per member and day is the natural choice at BiblioRed. But a very heavy user could generate hundreds of events a day, so a cap is needed: when a container reaches, say, 500 events, another one is opened (ACT-14-2026-08-02-2). A container with no cap becomes an unbounded array, which is precisely the anti-pattern of the next section.

When to apply it: series of events, telemetry, measurements, audit logs. It is the document answer to the problem we assigned to Cassandra in 03-02, and the reason BiblioRed can solve it without deploying another database.

Problem. 99.8% of BiblioRed's materials have fewer than 50 reviews, and for them embedding them would be perfect. But three or four bestsellers have thousands. If you design for the extreme case, you penalize the 39,996 normal materials; if you design for the normal case, the four extremes break the system.

Solution. Design for the common case and flag the exceptional ones with a flag that activates an alternative path.

Cost: the application has two read paths, and that is real complexity that has to be documented and tested. That is why this pattern is applied only when the distribution really is asymmetric and the extreme case is a tiny minority. If 20% of materials overflow, there is no outlier: there is a bad design and it is time to reference for everybody.

Problem. A material's record shows its average score. Computing it on every visit means going through its 812 reviews with an aggregation, for a page that is requested thousands of times a day.

Solution. Store the already computed result in the document and update it when the source data changes.

Notice score_sum: storing the sum as well as the average makes it possible to update it incrementally, without going through anything.

Risk: the computed field can drift away from reality if some write fails or if a review is deleted without being discounted. The usual defense: a nightly process that recomputes from scratch and corrects. A counter that only goes up never finds its way back on its own.

When to apply it: when the read/write ratio is very high. Here it is thousands to one; the pattern pays for itself.

The number one anti-pattern, and the easiest one to commit.

What happens, in order of appearance: the document grows until it approaches the 16 MB limit; every $push forces the rewriting of an ever-larger document; reads transfer megabytes in order to use two fields; the indexes over the array explode in size; and one day a write fails with BSONObjectTooLarge and there is no quick fix.

Warning sign: if you cannot state the maximum number of elements an array will have, do not embed it. Reference or bucket.

Even with no unlimited arrays, a document can put on weight by accumulation: the full synopsis, the cover in base64, the text extracted from the PDF, the change history... all inside the material's record.

Consequence: every read of the record —to show the title and the thumbnail cover— transfers the whole document from disk to memory and from there to the network. The server's cache fills up with data nobody looks at, and documents that are actually used get evicted.

Rule: large data that is rarely queried goes into its own collection, or straight out of the database —images into an object store or a file system, with the URL in the document—.

The opposite extreme: 17 million documents of 80 bytes. The per-document overhead (identifier, index entries, metadata) exceeds the useful data, the indexes do not fit in memory and range queries force the reading of millions of scattered documents.

Solution: the bucket pattern of section 8.

It is the most expensive anti-pattern because it does not show its face: the system works, it just works worse than PostgreSQL would.

That code is a relational schema written in MongoDB, and it inherits the worst of both worlds: the slowness of joining without the optimizations of a mature relational planner, and the document database's lack of referential integrity. If your design ends up here, the right conclusion is not "the pipeline needs optimizing": it is "this domain wanted PostgreSQL".

$lookup is legitimate for occasional reports and batch processes. It is not legitimate as the habitual mechanism of the main read path.

The flexible schema is an advantage as long as the team is disciplined. MongoDB lets you recover part of the safety net voluntarily and gradually, which is exactly what is needed: strong rules where they matter, freedom where it suits.

Proof that it works:

Three errors caught on the write, which is exactly where we wanted them. The one about the date as a string is the most valuable: it is the mistake from lesson 03-01 that ruins every later aggregation, and here it does not even get in.

The two behavior parameters:

Recommended strategy for a collection that already has data: start with validationAction: "warn" to discover how many documents would fail without breaking anything, fix them, and only then move to error. And use moderate while there are still old documents to migrate, so as not to block updates of what does not yet comply.

What $jsonSchema does not do, so as not to create false expectations: it does not check that material_id points at an existing material. Referential integrity still does not exist. It validates shape, not references.

In a relational database, changing the shape of the data is an ALTER TABLE that affects every row at once, with its lock and its window. In a document database there is a far more comfortable alternative: migrate nothing and live with several versions.

The technique is simple and it consists of one field:

The application reads the field and knows what to expect:

Three migration strategies, in order of aggressiveness:

The indispensable warning: living with several versions has a cost, and it is the code that manages them. If the team accumulates six active versions, the normalization function becomes a maze of conditionals nobody dares touch. Live with two, maybe three, and close your migrations: when the count of an old version reaches zero, delete its branch of code.

Everything said about modeling assumes that the queries are resolved efficiently, and that depends on indexes in MongoDB just as much as in PostgreSQL.

The good news is that the logic is the same one you will learn in lesson 06-03: an index is an auxiliary structure —usually a B-tree— that avoids going through all the data; it speeds up reads, slows down writes, takes up space, and the order of the fields in a composite index determines which queries it can serve.

The document-specific quirks, in four lines:

• You can index any field, even a nested one: db.reviews.createIndex({ "member.member_id": 1 }).
• You can index the content of an array (a multikey index): one entry per element. That is what makes searching by tag fast.
• The TTL index deletes documents automatically after a period of time, and it is what BiblioRed will use to expire activity after two years.
• explain() is the equivalent of EXPLAIN in SQL and it tells you whether the query used an index or went through the whole collection.

We will not go any deeper: indexes have a lesson of their own in module 6.

Here is the result of applying everything above. Three collections in MongoDB's bibliored database, with every decision justified.

Aggregate root: the material. Answers: C1 (full record) and C4 (search).

And a document of another type, in the same collection, so the heterogeneity is visible:

Indexes: { normalized_title: 1 }, { tags: 1 }, { type: 1, "rating.average": -1 }, { "authors.author_id": 1 }.

Aggregate root: the review. Answers: C2, C3 and C5.

Indexes: { "material.material_id": 1, helpful_votes: -1 }, { "member.member_id": 1, date: -1 }, { status: 1, date: -1 }, { tags: 1 }.

Aggregate root: the set of a member's events on one day. Answers: C6, C7 and C8.

Indexes: { member_id: 1, day: -1 }, { day: 1 } with expireAfterSeconds: 63072000, { "events.material_id": 1 }.

Look at the style of the arrows: the solid ones are copies of data that have to be kept consistent; the dashed ones are references the application resolves when needed. Every solid arrow is a consistency responsibility somebody has to take on in the code, and that is why it is best that they are few and documented. Here there are exactly two.

Mistake 1: starting by drawing entities. It is the reflex we bring from the relational model and here it leads to normalized collections stitched together with $lookup. Always start from the list of queries.

Mistake 2: embedding "because that is what you do in MongoDB". Embedding is right for one-to-few. For one-to-many and one-to-squillions it is a time bomb that goes off in production, not in development.

Mistake 3: duplicating without deciding the data's category. Every duplicated field has to be classified: immutable, frozen historical or live with propagation. If you do not write it down, in six months nobody will know whether it has to be updated.

Mistake 4: trusting that the flexible schema documents itself. It does not. Write the $jsonSchema even if you set it to warn: it is executable documentation of the collection's contract.

Mistake 5: testing the design only with toy data. A design with 200 documents always looks good. Generate 500,000 synthetic documents with the real expected distribution —outliers included— and measure before signing off on anything.

Mistake 6: forgetting that the application is now the one responsible. There is no FOREIGN KEY preventing a review about a nonexistent material. If deleting a material has to drag its reviews along, you are the one who writes that CASCADE.

Tip 1: write a decision sheet for every collection. Aggregate root, the queries it serves, what is embedded and why, what is duplicated and of which category, indexes. Half a page per collection that saves weeks.

Tip 2: name fields consistently, and short where they repeat a lot. Inside an array of thousands of elements, t instead of timestamp saves real megabytes. Outside of that, prioritize readability.

Tip 3: put the schema_v field in from the very first document. It costs four bytes and the day you need it —and you will need it— it will save you a blind bulk migration.

Tip 4: review the design when the queries change, not when the domain changes. It is the corollary of section 1 and the most important warning in the lesson: in the document world, a change in how the data is used can force a redesign even though the data is the same.

BiblioRed wants to add book clubs: groups with a name, a meeting branch, between 8 and 25 member members, one book assigned each month and a comment thread for each book read (some 30–60 comments per book, and the club may have been running for years). Decide for each relationship whether you embed or reference, justifying it with the six criteria of section 3, and write the example document for the clubs collection.

This document has four design problems. Identify them, say which anti-pattern or bad criterion each one represents and propose the corrected design.

Write the $jsonSchema validation for the activity collection designed in section 15.3, requiring: a mandatory positive integer member_id; a mandatory day of date type; an integer event_count between 0 and 500; a mandatory events array of at most 500 elements, where each element must have t (a date) and type (one of search, record, filter, reservation, download). Then explain why it would be advisable to deploy it with validationAction: "warn" rather than with "error".

Solution 1

A club and its members → embed. Cardinality of 8 to 25, with a natural cap imposed by the club's own rules (criterion 1: few). They are always shown with the club's record and they are not queried separately (criterion 2). They change little: somebody joins or leaves a few times a year (criterion 3). They take up a few kilobytes (criterion 4). Growth is bounded by the maximum number of seats (criterion 5). And joining and leaving have to stay consistent with the count of free seats, which favors atomicity within the same document (criterion 6). Six out of six in favor of embedding, with an extended reference to the member's name.

A club and its reading calendar → embed, but keep an eye on it. Twelve books a year. After five years that is sixty elements: it is still one-to-few and it fits comfortably. It is shown in full on the club's record ("what we have read"). It gets embedded, with a note that if a club ever exceeded ~200 elements it would be worth separating the old history.

A club and each book's comments → reference. Here criterion 5 rules: 40 comments per book × 12 books a year × several years is growth with no cap (criteria 1 and 5). They also have a life of their own —they are moderated, replied to, linked— (criterion 2), they change frequently (criterion 3) and they do not need to change atomically with the club (criterion 6). Their own club_comments collection, with the subset of the three most recent embedded in the club so "latest activity" can be shown without a second query.

Solution 2

A deliberate detail: the _id is 14, the same identifier as PostgreSQL's member_id. When an entity exists in both databases, sharing the identifier is the decision that causes the fewest headaches.

Solution 3

Notice two things about the design of the validation. First, maxItems: 500 turns the cap that in section 15.3 was only a convention into a rule checked by the server: the unbounded array stops being possible by oversight. Second, the fields term, material_id, field and value are not in required: each type of event uses some and not others, and that heterogeneity is precisely what makes this data live in MongoDB.

Why deploy with warn first. The collection already has data written before the validation existed, and it is practically certain that some of it does not comply: old events with t stored as a string, a type that was called "view" before it was renamed, containers generated in testing with more than 500 elements. With validationAction: "error" those writes would start failing all at once in production and on the system's most frequent write path (C6, event logging, with a requirement of under 10 ms). With warn, MongoDB accepts the write and notes the breach in the log: over a few days the warnings are collected, the problem is quantified, the old documents and the code paths generating them are fixed, and only then do you move to error with the certainty that nothing will break.

And validationLevel: "moderate" complements the strategy: while the cleanup lasts, updates of documents that already failed are not blocked, so the correction process can work without fighting its own validation.

This has been the design lesson, and its content can be summarized like this:

• The order is inverted: in the relational model you model the domain and then query it; in the document model you start from the list of queries and design documents that resolve them in a single access. The same domain admits different designs depending on its use.
• An aggregate is read together, written together and has a root. And above all: it is the boundary of atomicity. What is inside the document changes in one piece; what is outside needs a transaction or tolerance of lag.
• Embed or reference is decided with six criteria: cardinality, whether the child is queried separately, volatility, size against the 16 MB limit, bounded or unlimited growth, and the need for joint atomicity.
• One-to-few → embed. One-to-many → reference with a subset in the parent. One-to-squillions → reference only from the child, with no list in the parent.
• Duplication is a tool, not a mistake, and every duplicated field belongs to a category: immutable (free), frozen historical (semantically correct) or live (requiring immediate propagation, deferred propagation or a re-read). Duplicate what is displayed, never what is used to decide.
• Five patterns: extended reference (copy the few fields that get rendered), subset (the first N in the parent), bucket (series of events in containers per period, with upsert and $setOnInsert), outlier (a flag for the overflowing minority) and computed field (store the aggregate and maintain it with $inc).
• Four anti-patterns: unbounded arrays, giant documents, massive collections of tiny documents and MongoDB used as a relational database by way of $lookup —whose correct diagnosis is usually "this wanted PostgreSQL"—.
• $jsonSchema voluntarily and gradually recovers part of the lost safety net: types, ranges, required fields, patterns and closed value sets, with adjustable validationLevel and validationAction. It does not validate references: referential integrity is still the application's business.
• Versioning with schema_v allows evolution without a bulk migration, with lazy, background or bulk strategies. Live with two or three versions and close your migrations.
• And the deliverable: catalog (rooted in the material, with free metadata per type, computed rating, featured_reviews as a subset and availability copied from PostgreSQL), reviews (rooted in the review, with material and member as extended references and votes embedded for atomicity) and activity (rooted in the member-day set, with the bucket pattern, a deterministic _id, a cap of 500 events and a TTL index at two years).

We now have the course's two halves built: biblioredb in PostgreSQL and bibliored in MongoDB, each with the design it deserves. In lesson 03-04, Comparison between Relational and Non-Relational Databases, we put them face to face dimension by dimension and add the theoretical pieces we have been postponing: the CAP theorem without the usual misunderstanding and its refinement PACELC, the contrast between ACID and BASE, what eventual consistency really means for the reader who has just published a review, MongoDB's tunable consistency levels, and the decisive nuance that the border has blurred —PostgreSQL stores documents with jsonb and MongoDB has multi-document transactions—. We will close with an honest decision guide, the most repeated myths dismantled and the name of the architecture BiblioRed has arrived at: polyglot persistence.