Docs Menu
Docs Home
MongoDB Manual
/ /

Document and Schema Versioning

On this page

  • Use Cases
  • Tasks
  • Learn More

Your schema may need to change over time to account for changing technical requirements. When your schema changes, you can use schema design patterns to retain your original document structure. By retaining historical versions of documents and schemas, you avoid performance-intensive schema migrations and downtime.

Versioning patterns are useful when your data requirements change and you want to keep historical data in its original form. For example:

  • An insurance company lets customers modify their policy to insure additional items. When a customer changes their policy, the insurance company keeps a record of the policy changes over time. The company uses the Document Versioning pattern to track policy revisions by storing each update in a separate document. Historical data is stored in a separate collection, and does not impact queries on current data.

  • A company stores customer contact information. In the original schema, various contact methods like homePhone, cellPhone, and email are stored in individual fields. Over time, fewer customers have homePhone numbers, so the company modifies the schema to move contact information to a generic contacts document, which has variable subfields. After the schema change, the company implements the Schema Versioning pattern, and adds a schemaVersion field to tell the application how it should query each document.

To learn how to keep a history of document and schema changes, see these pages:

← Group Data with the Outlier Pattern