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. 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.