Cosmos DB Data Model: Containers, Items, and Partition Keys

The data hierarchy: account, database, container, item

A Cosmos DB account is the top-level Azure resource. It defines the region (or regions for multi-region replication), consistency level, and connection credentials. An account can contain multiple databases, but throughput and storage are provisioned at the container level (or optionally shared at the database level).

A database is a namespace that groups related containers. It has no schema and no throughput of its own unless you use database-level throughput sharing. You can have multiple databases in one account to separate applications logically while sharing infrastructure costs.

A container is the unit of scalability in Cosmos DB. It maps to a collection in MongoDB API terms, or a table in Cassandra API terms. Throughput (RU/s) is provisioned per container. A container has exactly one partition key, which determines how data is distributed internally.

An item is a single JSON document stored in a container. It has no predefined schema — different items in the same container can have different fields. Every item has system properties that Cosmos DB manages automatically.

# Create an account
az cosmosdb create \
  --resource-group myResourceGroup \
  --name mycosmosaccount \
  --kind GlobalDocumentDB \
  --locations regionName=eastus

# Create a database
az cosmosdb sql database create \
  --resource-group myResourceGroup \
  --account-name mycosmosaccount \
  --name myDatabase

# Create a container with a partition key
az cosmosdb sql container create \
  --resource-group myResourceGroup \
  --account-name mycosmosaccount \
  --database-name myDatabase \
  --name orders \
  --partition-key-path /customerId \
  --throughput 400

JSON document structure and system properties

Items in Cosmos DB are JSON documents. There is no schema enforcement — you can store whatever JSON structure you need. Cosmos DB adds several system-managed properties to every item:

{
  "id": "order-8f3a2c1b",
  "customerId": "cust-00192",
  "orderDate": "2026-03-19T14:30:00Z",
  "status": "shipped",
  "total": 149.99,
  "items": [
    {
      "productId": "prod-441",
      "name": "Wireless Keyboard",
      "quantity": 1,
      "price": 79.99
    },
    {
      "productId": "prod-882",
      "name": "USB Hub",
      "quantity": 2,
      "price": 34.99
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Seattle",
    "state": "WA",
    "zip": "98101"
  },
  "_rid": "AbCdEfGhIjKl==",
  "_self": "dbs/myDatabase/colls/orders/docs/order-8f3a2c1b",
  "_etag": "\"00000000-0000-0000-1234-abcdef012345\"",
  "_attachments": "attachments/",
  "_ts": 1742393400
}

The id field is required and must be unique within a logical partition (a partition key value). The combination of id and partition key value uniquely identifies an item in the entire container. System properties prefixed with _ are managed by Cosmos DB: _ts is the Unix timestamp of the last modification, and _etag is used for optimistic concurrency control.

Partition keys: how data distribution works

The partition key is the field in your documents that Cosmos DB uses to distribute data across physical partitions. When you write an item, Cosmos DB hashes the partition key value and routes the item to the appropriate physical partition. Items with the same partition key value are always stored in the same logical partition and on the same physical partition.

Cosmos DB divides container storage and throughput across physical partitions. Each physical partition holds up to 50 GB and serves up to 10,000 RU/s. As your container grows beyond these limits, Cosmos DB splits physical partitions automatically. This split is transparent — but the quality of your partition key determines whether the split distributes load evenly or creates new hot partitions.

A good partition key has:

• High cardinality — many distinct values. A partition key with 10 possible values can only spread load across 10 logical partitions. A partition key with millions of distinct values can spread load across many partitions.
• Even distribution — roughly equal data volume and request rate across all key values. An even distribution means no single partition gets more than its share of traffic.
• Alignment with query patterns — if most queries filter by a specific field, using that field as the partition key allows Cosmos DB to satisfy the query from a single partition (a “single-partition query”), which is cheaper in RUs and faster.

The hot partition problem

A hot partition occurs when too much read or write traffic concentrates on a single partition key value. Throughput is distributed evenly across all partitions, so if 80% of your writes go to one partition key, that partition uses 80% of the container’s RU budget while the other partitions sit mostly idle. When that hot partition exhausts its share of RUs, requests are rate-limited (HTTP 429 responses) even if the overall container throughput looks underutilized.

Common hot partition patterns to avoid:

• Partition key on a low-cardinality field — using status as the partition key when 95% of items have status “active”.
• Partition key on a date without bucketing — using date when all current writes are for today’s date.
• Partition key on a tenant ID in a multi-tenant system — if one tenant generates 10x the traffic of all others, their partition is a hot partition.

TTL, indexing policy, and container settings

Cosmos DB supports automatic deletion of items via TTL (Time To Live). Set a default TTL on the container and items will be deleted automatically after that many seconds. Items can also override the container TTL with their own ttl field.

# Enable TTL on a container (delete items after 7 days by default)
az cosmosdb sql container update \
  --resource-group myResourceGroup \
  --account-name mycosmosaccount \
  --database-name myDatabase \
  --name orders \
  --ttl 604800

{
  "id": "temp-session-9f1a",
  "userId": "user-4421",
  "data": "...",
  "ttl": 3600
}

TTL is useful for session data, rate-limiting counters, temporary tokens, and any data with a natural expiry. Deleted items consume RUs for deletion proportional to the item size.

The indexing policy determines which fields Cosmos DB indexes. By default, all fields are indexed, which enables flexible queries but increases write RU cost and storage. For write-heavy containers, reduce indexing by specifying only the paths you actually query:

{
  "indexingMode": "consistent",
  "includedPaths": [
    { "path": "/customerId/?" },
    { "path": "/orderDate/?" },
    { "path": "/status/?" }
  ],
  "excludedPaths": [
    { "path": "/*" }
  ]
}

This indexing policy indexes only customerId, orderDate, and status, and excludes everything else (including large nested arrays that would otherwise inflate the index).