The Polymorphic and Schema Versioning Patterns

One of MongoDB's biggest advantages over SQL is that documents in the same collection do not need to share the same fields. This enables the Polymorphic Pattern — storing documents of fundamentally different types in a single collection. Think of a vehicles collection that holds cars, trucks, and motorcycles: all have make and year, but only cars have numberOfDoors and only motorcycles have hasSidecar.

The key to the Polymorphic Pattern is a type discriminator field — a field (commonly named type, kind, or _type) that identifies which subtype a document represents. All application code and indexes can use this field to dispatch behaviour correctly. Index the discriminator field so queries filtering by type execute as IXSCAN rather than COLLSCAN.

Application code handles polymorphic documents with a factory or strategy pattern: inspect the type field and delegate to the appropriate handler class or function. In Node.js/Mongoose, you can use discriminators — a built-in Mongoose feature that defines sub-schemas for each document type within a single collection, automatically setting and reading the discriminator key.

Use the Polymorphic Pattern when different subtypes share most of their fields and are queried together frequently. A single vehicles collection makes it easy to ask 'show all Toyota vehicles regardless of type'. Use separate collections when subtypes are almost entirely different, rarely queried together, or have vastly different indexing needs. Polymorphism trades simpler cross-type queries for slightly more complex per-type logic.

Applications evolve and schemas change, but you cannot stop the world to migrate every document at once. The Schema Versioning Pattern adds a schema_version field to every document. Old documents have version 1 (or no version field, treated as v1), new documents have version 2. Application code checks the version and applies the appropriate transformation, enabling a gradual zero-downtime migration.

When reading documents, check schema_version and handle each version appropriately in a transform layer. Version-agnostic code calls the transform function and always receives a canonical object. This decouples the application logic from the stored document shape and gives you time to migrate documents in the background without a hard cutover.

Lazy migration upgrades documents to the new schema as they are naturally accessed. When a document is read and transformed to v2 in memory, write the v2 shape back to the database. Over time, all active documents migrate without a bulk script. Inactive documents can be migrated by a background job. This approach is low-risk — no single large migration to coordinate or roll back.

For faster migration, run a background script that iterates over all v1 documents in batches using a cursor, transforms them, and writes back using bulkWrite(). Process documents in batches (e.g., 1,000 at a time) to avoid overwhelming the server. Run during off-peak hours and include a delay between batches to throttle impact on production traffic.

These two patterns can work together. A polymorphic collection might have both a type discriminator (for subtype dispatch) and a schema_version (for evolutionary migration within each subtype). When documents of type 'car' gain a new required field in v2, the version field tracks which cars have been migrated and which still carry the old shape.

Indexes in a polymorphic collection apply across all document types. A partial index (using partialFilterExpression) lets you index a field only for documents of a specific type — for example, indexing numberOfDoors only for car documents. This avoids indexing null/missing values for types that do not have the field, keeping the index small and efficient.

A common mistake is to update the schema without tracking versions, assuming all documents will be migrated before the new code deploys. In practice, migrations are rarely 100% complete at deploy time. Code that blindly reads a field that may not exist in older documents will throw null pointer errors or produce incorrect results. Always include a version check or a safe fallback when reading potentially-missing fields.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: the Polymorphic Pattern stores different document subtypes in one collection using a type discriminator field, enabling efficient cross-type queries and Mongoose discriminator support, the Schema Versioning Pattern tracks document shape evolution with a version field, enabling lazy or background migration without downtime, and partial indexes make polymorphic collections efficient by indexing fields only for the types that have them. Next up we cover the Outlier and Tree Structure Patterns.