Modeling Data in Azure Cosmos DB

Azure Cosmos DB is a globally distributed, multi-model database service. Understanding how to effectively model your data is crucial for performance, scalability, and cost-effectiveness. This document explores best practices and common patterns for data modeling in Cosmos DB.

Core Concepts

Azure Cosmos DB stores data in items, which are JSON documents. These items are grouped into containers. Containers are the fundamental unit of provisioned throughput and storage. Items within a container can have different schemas, providing schema flexibility.

Partitioning Strategy

Choosing a good partition key is essential for distributing your data and requests evenly across logical partitions. A well-chosen partition key can significantly improve query performance and scalability.

Relationships between Data

Azure Cosmos DB excels at storing denormalized data. However, there are scenarios where relationships need to be managed.

1. Embedded Documents (Denormalization)

This is the most common and recommended approach for many scenarios. Embed related data directly within the parent document. This reduces the need for joins and improves read performance. 


{
    "id": "user123",
    "name": "Alice Smith",
    "email": "alice.smith@example.com",
    "addresses": [
        {
            "street": "123 Main St",
            "city": "Anytown",
            "zip": "12345"
        },
        {
            "street": "456 Oak Ave",
            "city": "Otherville",
            "zip": "67890"
        }
    ],
    "orders": [
        {
            "orderId": "ord987",
            "orderDate": "2023-10-26",
            "totalAmount": 45.99
        }
    ]
}

2. Referenced Documents (Normalization)

For very large or frequently updated related data, or when data is shared across multiple parent documents, consider normalization. This involves storing related data in separate documents or containers and referencing them using IDs. This approach requires multiple requests to fetch related data. 


// User Document
{
    "id": "user456",
    "name": "Bob Johnson",
    "email": "bob.j@example.com",
    "defaultAddressId": "addr789"
}

// Address Document (in a separate container or same container with partition key difference)
{
    "id": "addr789",
    "userId": "user456",
    "street": "789 Pine Ln",
    "city": "Somewhere",
    "zip": "11223"
}

Common Modeling Patterns

1. Single Container with Various Document Types

Use a single container and add a documentType field to distinguish between different types of entities (e.g., users, products, orders). This is effective when entities share a common partition key and have some overlapping properties.

Tip: Use a documentType field to easily query specific types of documents.

2. Many-to-Many Relationships

For many-to-many relationships, consider an intermediary "join" document. 


// Document 1: Course
{
    "id": "course1",
    "title": "Introduction to Cosmos DB"
}

// Document 2: Student
{
    "id": "student1",
    "name": "Charlie Brown"
}

// Document 3: Enrollment (Join Document)
{
    "id": "enrollment1",
    "courseId": "course1",
    "studentId": "student1",
    "enrollmentDate": "2023-10-26"
}

3. Time Series Data

For high-volume time series data, consider partitioning by a time-based field (e.g., day, hour) and using a monotonically increasing value as a sort key within that partition.

Important: Always test your data model with realistic read and write patterns to ensure it meets your performance requirements.

Next Steps