Overview of Partitions

What are partitions?

Partitions are the primary tool Cosmos DB uses to provide horizontal scaling. The database replicates and distributes our data into different servers (based on the configuration) to achieve great response times. However, it doesn’t duplicate the whole dataset everywhere, because each node has limits. Instead, it divides the data into distinct subsets and distributes them. These subsets are called logical partitions.

Note: All the documents in a logical partition have the same partition key.

We don’t know yet about partition keys, but for now, keep in mind that:

• The partition key path is set on container creation and is immutable.

• The value of the partition is in the document itself.

• Partitions are created/deleted automatically.

Logical partitions

Let’s see an example! Imagine we create an invoices container, and we specify /customerId as the partition key path.

When we add a new document, Cosmos DB does the following:

• Reads the value of the customerId field.

• Looks for a specific partition for that value or creates one if there are none.

• Creates the document in the correct partition.

This process results in the following:

• One partition for each customer.

• All invoices in a partition have the same partition key value (customerId).

An abstract example of how partitions would look like is as follows: