Skip to content
Tutorials Center
My learning

Topics

Lesson 42 of 70 ยท Schema design

Schema Design Patterns

Learn eight MongoDB schema design patterns: subset, bucket, computed, extended reference, outlier, polymorphic, attribute and schema versioning, with runnable demos.

After a while, the same schema problems come up in project after project: a document that carries too much history, a time series that creates millions of tiny documents, a report that sums the same numbers on every request, a catalogue whose products all have different fields. The MongoDB community has given the solutions names, called schema design patterns. A pattern is not a feature you turn on. It is a way of shaping documents, plus the updates and queries that go with it.

This lesson introduces eight of them: subset, bucket, computed, extended reference, outlier, polymorphic, attribute and schema versioning. Each gets a problem, the idea, the real mongosh operation, and where it fits, and the TryIts apply the ideas with plain JavaScript on arrays of documents.

The mongosh snippets are real and shown read-only (they use update operators you will meet in Updating Documents and Updating Arrays). The TryIts are stand-ins that perform the same reshaping in JavaScript, so you see the shape of the data before and after, not a database at work.

Keep documents lean and cheap to read

Subset Embed only the hot part of a big list.
Bucket Group many small records into one document.
Computed Store totals so reads need no maths.
Extended reference Copy a few fields next to the id.
1 / 2

Subset pattern

Problem. A product has thousands of reviews. The product page shows the three latest, but if reviews are embedded, every read loads thousands of them. If they are in their own collection, every page needs a second query.

Idea. Embed only the subset you display, and keep the complete set in a separate collection. The product document stays small, the page needs one read, and the full history is one query away.

JavaScript
db.products.updateOne(
  { _id: 1 },
  {
    $push: { latestReviews: { $each: [review], $position: 0, $slice: 3 } },
    $inc: { reviewCount: 1, ratingSum: review.rating }
  }
)
db.reviews.insertOne(review)   // the full set lives here

$position: 0 puts the new review first and $slice: 3 trims the list to three. The price is some duplication and two writes per review (Atomicity and Single-Document Writes discusses that).

Computed pattern

Problem. A page shows an average rating, a total or a count. Computing it from thousands of documents on every view is wasteful, especially when reads vastly outnumber writes.

Idea. Do the arithmetic when data changes and store the result: reviewCount and ratingSum above (the average is ratingSum / reviewCount), a running order total, a view counter incremented with $inc. Use it when the same result is read often and the inputs change comparatively rarely, and remember the stored number must be updated by every code path that changes its inputs.

Extended reference pattern

Problem. An order must show the customer's name and the product title. Referencing means a lookup per order for each of them.

Idea. Keep the reference and copy the few fields you always display next to it:

JavaScript
{
  _id: 1001,
  customer: { _id: 7, name: "Mia" },             // id plus the field the list needs
  items: [ { productId: "A1", title: "Trail Shoe", price: 89, qty: 1 } ]
}

Only copy fields that change rarely (a name) or that must stay as history (the price paid). Everything else stays in the source collection, reachable by the _id. The cost is that, for fields that do change, you need an update that fans out to the copies (see Embedding vs Referencing).

The first stand-in applies subset and computed together: it adds reviews one by one, keeps the latest three in the product, and maintains the count and average.

JS Subset and computed in one product document

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Bucket pattern

Problem. A sensor sends a reading every few seconds. One document per reading means millions of tiny documents, each with its own _id, overhead and index entries.

Idea. Group readings into buckets: one document per sensor per hour, holding an array of readings plus precomputed summary values. A bucket is capped (here at 200 readings), and when it is full, the next reading starts a new one.

JavaScript
db.readings.updateOne(
  { sensor: "s1", hour: 13, count: { $lt: 200 } },
  {
    $push: { readings: { m: 5, v: 21.4 } },
    $inc: { count: 1, sum: 21.4 },
    $min: { min: 21.4 },
    $max: { max: 21.4 }
  },
  { upsert: true }
)

If no matching non-full bucket exists, the upsert creates one. This is bucketing and the computed pattern together, and it fits time-series style data (Project: Event Logging with Bucketing and TTL). MongoDB also has dedicated time-series collections that apply similar ideas for you.

JS Bucketing readings with running summaries

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The eight readings land in three documents: hour 0 fills a four-reading bucket, a second hour-0 bucket takes the next two, and hour 1 starts its own. Averages and extremes are already stored, so a dashboard never touches the individual readings.

Outlier pattern

Problem. Almost every book has a few hundred readers, but a bestseller has millions. Designing every document for the bestseller wastes effort, and designing for the average breaks on the exception.

Idea. Keep the normal design and flag the exceptions. When a document exceeds a threshold, mark it and put the overflow elsewhere:

JavaScript
{ _id: "book-42", title: "A Hit", readers: [ /* first 1000 */ ], hasOverflow: true }
// readersOverflow: { bookId: "book-42", readers: [ ... ], page: 1 }

Application code checks hasOverflow and fetches the extra pages only for those few documents. The normal queries and indexes stay simple for the 99.9% of documents that are ordinary.

Polymorphic pattern

Problem. A content feed shows articles, videos and podcasts. They share some fields (title, tags) and differ in others. Three collections would force three queries and a merge.

Idea. Store them in one collection with a type field and type-specific fields, and let one query (or index on tags) return the mix. Code then branches on type. It is the document-database answer to "different shapes behind one interface".

Attribute pattern

Problem. Products have wildly different properties: a shirt has size and colour, a mug has capacity and material, a bag has volume. Indexing each possible field separately is hopeless, and a wildcard index may be too loose.

Idea. Move the odd fields into an array of { k, v } pairs, and index the pair once:

JavaScript
{ _id: 3, name: "Backpack", attrs: [ { k: "color", v: "red" }, { k: "volume_l", v: 25 } ] }

db.products.createIndex({ "attrs.k": 1, "attrs.v": 1 })
db.products.find({ attrs: { $elemMatch: { k: "color", v: "red" } } })

One index covers every attribute, and new attributes need no new indexes. $elemMatch keeps k and v in the same pair (Array Query Operators). Values of different types in one v field sort by type, so keep attribute values of the same name consistently typed.

Schema versioning pattern

Problem. Your schema changes over time, and a collection can hold millions of documents in old shapes. A migration that rewrites everything at once is slow and risky.

Idea. Put a schemaVersion field in each document. Application code reads any version, converts old shapes on the fly, and writes back the new shape when it next saves the document. A background job can finish the migration gradually, and db.users.find({ schemaVersion: { $lt: 2 } }) shows what is left.

The next two stand-ins show attributes, polymorphism and versioning on small data.

JS Attribute pattern: one shape for odd fields

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Polymorphic documents and schema versions

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Choosing patterns

Patterns solve specific tensions, so start from the symptom:

Symptom Try
Documents load too much for the common read Subset
Millions of tiny documents Bucket
The same sum or average computed on every read Computed
A read needs a lookup only for one or two fields Extended reference
A few documents break the design Outlier
Related things with different shapes Polymorphic
Many different optional fields Attribute
Schema keeps evolving Schema versioning

Patterns trade extra write work and some duplication for simpler, cheaper reads, so apply them where reads dominate and the access pattern is clear. They are not required for a small application, and a premature pattern is just complexity.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A product page shows the three latest reviews out of 10,000. Which pattern keeps the product document small and the page to one read?

    The subset pattern embeds only the part you display, the latest few reviews, and keeps the full set in its own collection.
  2. 2. Which pattern groups many small records, such as sensor readings, into one document per time window?

    Bucketing stores a capped array of records per document, often with precomputed summaries, which avoids millions of tiny documents.
  3. 3. Products have very different optional properties and you want one index to support queries on any of them. Which pattern fits?

    The attribute pattern stores properties as { k, v } pairs in an array, so a single compound index on attrs.k and attrs.v covers every property.
  4. 4. What does a schemaVersion field let you do?

    The version tells your code which shape it is looking at, so it can upgrade old documents on read or in a background job instead of one big migration.

Summary

  • Subset embeds only the hot part of a large list; computed stores results so reads need no arithmetic; extended reference copies a few stable fields beside an id.
  • Bucket groups many small records into capped documents with running summaries.
  • Outlier flags the rare giant document and moves its overflow elsewhere.
  • Polymorphic keeps different shapes in one collection with a type field; attribute turns odd fields into indexable { k, v } pairs.
  • Schema versioning marks each document with its shape version so you can migrate gradually.
  • Apply a pattern to fix a specific symptom, accepting extra write work and some duplication in exchange for cheaper reads.

Next, model connections between entities in Modeling Relationships.