Manage consistency levels in Azure Cosmos DB

This article explains how to manage consistency levels in Azure Cosmos DB. You learn how to configure the default consistency level, override the default consistency, manually manage session tokens, and understand the Probabilistically Bounded Staleness (PBS) metric.

As you change your account level consistency, ensure you redeploy your applications and make any necessary code modifications to apply these changes.

Configure the default consistency level

To learn more about the default consistency level, see Consistency levels in Azure Cosmos DB.

# Create a new account with Session consistency
az cosmosdb create --name $accountName --resource-group $resourceGroupName --default-consistency-level Session

# Update an existing account's default consistency
az cosmosdb update --name $accountName --resource-group $resourceGroupName --default-consistency-level Strong

# Create a new account with Session consistency
New-AzCosmosDBAccount -ResourceGroupName $resourceGroupName `
  -Location $locations -Name $accountName -DefaultConsistencyLevel "Session"

# Update an existing account's default consistency
Update-AzCosmosDBAccount -ResourceGroupName $resourceGroupName `
  -Name $accountName -DefaultConsistencyLevel "Strong"

Override the default consistency level

The service sets the default consistency level, but clients can override it. The consistency level can be set on a per-request basis, which overrides the default consistency level set at the account level.

.NET SDK

// 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
RequestOptions requestOptions = new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };

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

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

var response = await client.GetContainer(databaseName, containerName)
    .ReadItemAsync(
        item,
        new PartitionKey(itemPartitionKey),
        requestOptions);

Java V4 SDK

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildAsyncClient();

CosmosClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildClient();

Java V2 SDKs

// Override consistency at the client level
ConnectionPolicy policy = new ConnectionPolicy();

AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKey(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConsistencyLevel(ConsistencyLevel.Eventual)
                .withConnectionPolicy(policy).build();

// Override consistency at the client level
ConnectionPolicy connectionPolicy = new ConnectionPolicy();
DocumentClient client = new DocumentClient(accountEndpoint, accountKey, connectionPolicy, ConsistencyLevel.Eventual);

Node.js/JavaScript/TypeScript SDK

// Override consistency at the client level
const client = new CosmosClient({
  /* other config... */
  consistencyLevel: ConsistencyLevel.Eventual
});

// Override consistency at the request level via request options
const { body } = await item.read({ consistencyLevel: ConsistencyLevel.Eventual });

Python SDK

# Override consistency at the client level
connection_policy = documents.ConnectionPolicy()
client = cosmos_client.CosmosClient(self.account_endpoint, {
                                    'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Eventual)

Go SDK

Define consistency level at the request:

container, _ := c.NewContainer("moviesdb", "movies")

container.NewQueryItemsPager("select * from c", azcosmos.NewPartitionKey(), &azcosmos.QueryOptions{
		ConsistencyLevel: azcosmos.ConsistencyLevelEventual.ToPtr(),
})

container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), "Pulp Fiction", &azcosmos.ItemOptions{
		ConsistencyLevel: azcosmos.ConsistencyLevelStrong.ToPtr(),
})

Use Read Consistency Strategy

The ReadConsistencyStrategy feature (available in Java SDK v4.69+ and .NET SDK v3.46+) provides a more flexible way to control read consistency. Unlike the traditional ConsistencyLevel override which can only relax consistency, ReadConsistencyStrategy allows you to set any supported read-consistency strategy per-read, including stronger than the account default, without changing your account configuration.

Available strategies

Java SDK

Client-level default:

CosmosAsyncClient client = new CosmosClientBuilder()
    .endpoint(endpoint)
    .credential(new DefaultAzureCredentialBuilder().build())
    .readConsistencyStrategy(ReadConsistencyStrategy.LATEST_COMMITTED)
    .buildAsyncClient();

Per-request override (for example, during a detected outage):

CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setReadConsistencyStrategy(ReadConsistencyStrategy.EVENTUAL);
container.readItem(id, partitionKey, options, MyItem.class);

Per-request override for queries:

CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions();
queryOptions.setReadConsistencyStrategy(ReadConsistencyStrategy.LATEST_COMMITTED);

SqlQuerySpec querySpec = new SqlQuerySpec(
    "SELECT * FROM c WHERE c.category = @cat",
    new SqlParameter("@cat", "electronics"));
container.queryItems(querySpec, queryOptions, MyItem.class);

.NET SDK

Client-level default:

CosmosClient client = new CosmosClientBuilder(endpoint, new DefaultAzureCredential())
    .WithReadConsistencyStrategy(ReadConsistencyStrategy.LatestCommitted)
    .Build();

Per-request override:

ItemRequestOptions options = new ItemRequestOptions
{
    ReadConsistencyStrategy = ReadConsistencyStrategy.Eventual
};
var response = await container.ReadItemAsync<MyItem>(id, new PartitionKey(partitionKey), options);

Per-request override for queries:

QueryRequestOptions queryOptions = new QueryRequestOptions
{
    ReadConsistencyStrategy = ReadConsistencyStrategy.LatestCommitted
};
var iterator = container.GetItemQueryIterator<MyItem>("SELECT * FROM c", requestOptions: queryOptions);

ReadConsistencyStrategy vs ConsistencyLevel override

Utilize session tokens

One of the consistency levels in Azure Cosmos DB is session consistency. This level is the default level applied to Azure Cosmos DB accounts. When working with session consistency, every new write request to Azure Cosmos DB is assigned a new SessionToken. The CosmosClient uses this token internally with each read/query request to ensure that the set consistency level is maintained.

In some scenarios, you need to manage this session yourself. Consider a web application with multiple nodes, each node has its own instance of CosmosClient. If you want these nodes to participate in the same session (to be able to read your own writes consistently across web tiers) you would have to send the SessionToken from FeedResponse<T> of the write action to the end-user using a cookie or some other mechanism, and have that token flow back to the web tier and ultimately the CosmosClient for subsequent reads. If you're using a round-robin load balancer that doesn't maintain session affinity between requests, such as the Azure Load Balancer, the read could potentially land on a different node to the write request, where the session was created.

If you don't flow the Azure Cosmos DB SessionToken across, you could end up with inconsistent read results for a while.

Session tokens in Azure Cosmos DB are partition-bound, meaning they're exclusively associated with one partition. In order to ensure you can read your writes, use the session token that was last generated for the relevant items. To manage session tokens manually, get the session token from the response and set them per request. If you don't need to manage session tokens manually, you don't need to use these samples. The SDK keeps track of session tokens automatically. If you don't set the session token manually, by default, the SDK uses the most recent session token.

.NET SDK

var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"));
string sessionToken = response.SessionToken;

RequestOptions options = new RequestOptions();
options.SessionToken = sessionToken;
var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"), options);

Container container = client.GetContainer(databaseName, collectionName);
ItemResponse<SalesOrder> response = await container.CreateItemAsync<SalesOrder>(salesOrder);
string sessionToken = response.Headers.Session;

ItemRequestOptions options = new ItemRequestOptions();
options.SessionToken = sessionToken;
ItemResponse<SalesOrder> response = await container.ReadItemAsync<SalesOrder>(salesOrder.Id, new PartitionKey(salesOrder.PartitionKey), options);

Java V4 SDK

// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setSessionToken(sessionToken);
CosmosItemResponse<JsonNode> response2 = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();

// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class);
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setSessionToken(sessionToken);
CosmosItemResponse<JsonNode> response2 = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class);

Java V2 SDKs

// Get session token from response
RequestOptions options = new RequestOptions();
options.setPartitionKey(new PartitionKey(document.get("mypk")));
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);
readObservable.single()           // we know there will be one response
  .subscribe(
      documentResourceResponse -> {
          System.out.println(documentResourceResponse.getSessionToken());
      },
      error -> {
          System.err.println("an error happened: " + error.getMessage());
      });

// Resume the session by setting the session token on RequestOptions
RequestOptions options = new RequestOptions();
requestOptions.setSessionToken(sessionToken);
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);

// Get session token from response
ResourceResponse<Document> response = client.readDocument(documentLink, null);
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
RequestOptions options = new RequestOptions();
options.setSessionToken(sessionToken);
ResourceResponse<Document> response = client.readDocument(documentLink, options);

Node.js/JavaScript/TypeScript SDK

// Get session token from response
const { headers, item } = await container.items.create({ id: "meaningful-id" });
const sessionToken = headers["x-ms-session-token"];

// Immediately or later, you can use that sessionToken from the header to resume that session.
const { body } = await item.read({ sessionToken });

Python SDK

// Get the session token from the last response headers
item = client.ReadItem(item_link)
session_token = client.last_response_headers["x-ms-session-token"]

// Resume the session by setting the session token on the options for the request
options = {
    "sessionToken": session_token
}
item = client.ReadItem(doc_link, options)

Go SDK

// Get the session token from the create item response
resp, _ := container.CreateItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), movie, &azcosmos.ItemOptions{
	ConsistencyLevel: azcosmos.ConsistencyLevelSession.ToPtr(),
})

// Use the session token to read the item
container.ReadItem(context.Background(), azcosmos.NewPartitionKeyString("Quentin Tarantino"), movieId, &azcosmos.ItemOptions{
	SessionToken: resp.SessionToken,
})

Monitor Probabilistically Bounded Staleness metric

How eventual is eventual consistency? For the average case, we can offer staleness bounds with respect to version history and time. The Probabilistically Bounded Staleness (PBS) metric tries to quantify the probability of staleness and shows it as a metric.

To view the PBS metric:

1. Go to your Azure Cosmos DB account in the Azure portal.

2. Open the Metrics (Classic) pane, and select the Consistency tab.

3. Look at the graph named Probability of strongly consistent reads based on your workload (see PBS).

Next steps

Learn more about how to manage data conflicts, or move on to the next key concept in Azure Cosmos DB.

• Consistency Levels in Azure Cosmos DB
• Partitioning and horizontal scaling
• Manage conflict resolution policies
• Consistency tradeoffs in modern distributed database systems design
• High availability (Reliability) in Azure Cosmos DB for NoSQL
• Azure Cosmos DB service level agreements