--- title: "Data Modeling in Cosmos DB: When to Embed vs. Reference Documents" description: "Data Modeling in Cosmos DB: When to Embed vs. Reference Documents" author: "Lily Chitlangiya" published: 2026-09-17 updated: 2026-09-17 canonical: https://www.mindstick.com/forum/162180/data-modeling-in-cosmos-db-when-to-embed-vs-reference-documents category: "NoSQL Databases" tags: ["Data Modeling", "Cosmos DB NoSQL", "Embedding vs Reference", "Denormalization", "Document Database"] reading_time: 1 minute --- # Data Modeling in Cosmos DB: When to Embed vs. Reference Documents Designing schemas for NoSQL databases like Cosmos DB requires shifting away from relational normalization. Instead of dividing entities across table joins, developers must choose between embedding nested objects or creating separate referenced documents. ## When to Embed Child Documents Embedding stores related items within the same [JSON document](https://www.mindstick.com/forum/34569/json). Use this approach when: - There is a contained, 1-to-few relationship between entities (e.g., customer address list). - Data is queried and updated together frequently. - The total size of the combined JSON document stays well under the 2 MB Cosmos DB limit. ## When to Reference Separate Documents Referencing uses distinct documents linked by primary keys. Choose referencing when: - Entities have 1-to-many or many-to-many relationships without upper boundaries (e.g., user post comments). - Data items are updated independently and frequently, avoiding high RU write charges on huge documents. - Read patterns require fetching parent documents without overhead from large child collections. By balancing read efficiency and write payload size, you optimize both query performance and billing costs. --- Original Source: https://www.mindstick.com/forum/162180/data-modeling-in-cosmos-db-when-to-embed-vs-reference-documents Copyright © MindStick Software Pvt. Ltd. This Markdown version is provided for developers, AI systems, and offline reading.