The Cosmos DB is distributed database offering from Azure. The Cosmos DB offers high availability, low latency. There is a fundamental trade off between read consistency vs availability, latency and throughput.

In this article, we will have look at what is consistency level and how does it affects availability and performance of the applications.

Consistency Levels

Most of the databases offer two consistency levels – strong and eventual.

In strong consistency, you can not read updated data until all the copies of data are updated with latest update. In eventual consistency, the read call may return the previous state of data.

Instead of providing only two consistency levels, Azure Cosmos DB assumes the consistency levels as a spectrum. The eventual and strong consistencies are the opposite ends of the spectrum.

Azure Cosmos DB offers 5 consistency levels –

• Strong
• Bounded Staleness
• Session
• Consistent Prefix
• Eventual

These consistency levels are region agnostic. They are applied irrespective of the location from where the read or write requests are issued.

Read consistency applies to a single read operation scoped within a partition-key range or a logical partition. The read operation can be issued by a remote client or a stored procedure.

Strong Consistency

The reads are guaranteed to see the most recent committed version of an item. A client never sees uncommitted or partial writes. So, uses are always guaranteed to read the most recent committed write.

Bounded Staleness Consistency

The reads are guaranteed to honor the consistent-prefix guarantee. The reads might lag behind writes by at most “K” versions (i.e., “updates”) of an item or by “T” time interval. 

Bounded staleness offers total global order except within the “staleness window.” The monotonic read guarantees exist within a region both inside and outside the staleness window. 

Session Consistency

Within a single client session reads are guaranteed to honor the consistent-prefix, monotonic reads, monotonic writes, read your writes and write your read guarantees. The other people will see eventual consistency.

This is the default consistency level on the cosmos DB account.

Consistent Prefix

Consistent prefix consistency level guarantees that reads never see out-of-order writes.

Eventual Consistency

There is no ordering guarantee for reads. The replicas will eventually converge if there are no further writes.

Set Default Consistency Levels

You can set the default consistency level while creating the Cosmos DB account. Alternatively, if you already have created the Cosmos DB account, you can update the default consistency level.

Below are the Azure CLI commands for both scenarios:

# create with a default consistency
az cosmosdb create --name CosmosDbAccount --resource-group Samples --default-consistency-level Session

# update an existing account's default consistency
az cosmosdb update --name CosmosDbAccount --resource-group Samples --default-consistency-level Eventual

You can also set default consistency level using Portal.

You can navigate to your Cosmos DB account and then open Default Consistency pane. You can set the required consistency level and then you can click on Ok to save as shown in below snapshot.

Overriding default consistency level

Clients can override the default consistency level that is set by the service. Consistency level can be set on a per request, which overrides the default consistency level set at the account level. Below is the sample .NET code which overrides the default consistency level.

// Override consistency at the client level
documentClient = new DocumentClient(new Uri(endpoint), authKey, connectionPolicy, ConsistencyLevel.Eventual);

// Override consistency at the request level via request options
var requestOptions = new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };

var response = await client.CreateDocumentAsync(collectionUri, document, requestOptions);

I hope this article helps you to understand what the consistency levels are and how to set them on the Cosmos DB account. Let me know your thoughts.