The latest updates to the Azure Cosmos DB .NET SDK bring a powerful new feature with the release of version 3.37.0: the ExcludeRegions request option. This enhancement allows developers to exclude specific regions from their preferred locations when making a request, enabling more precise and efficient request routing. Similarly, the Azure Cosmos DB Java SDK has also incorporated this feature in its version 4.47.0. With these updates, users can now exercise finer control over their data access patterns, ensuring optimal performance and reliability for their applications.

What is ExcludeRegions?

ExcludeRegions allows you to have more control over which region your requests are routed to when using Azure Cosmos DB in your applications. By specifying a list of the regions you would like to exclude in the ExcludeRegions property of the RequestOptions objects, the SDK will ensure that the request, including any cross regional retries, are not routed to any regions in that list. If all regions are included in the list, then the request will be routed to the primary/hub region.

Currently, the SDK has the ApplicationPreferredRegions list in the CosmosClientOptions. This allows you to specify an ordered regions list where SDK will only attempt to perform operations from the regions specified in preferred locations in order, failing over to the next valid region in the list if the request fails. The ExcludeRegions option allows you to bypass the order of this list on a per-request level and should be used in conjunction to PreferredLocations to help route your requests. In the example below, we show how to create a CosmosClient instance that uses ApplicationPreferredRegions and how to bypass that list using the ExcludeRegions option:

CosmosClientOptions clientOptions = new CosmosClientOPtions()
{
  ApplicationPreferredRegions = new List<string> {"West US", "Central US", "East US"};
}

CosmosClient client = new CosmosClient(connectionString, clientOptions);

Database db = client.GetDatabase("myDb");
Container container = db.GetContainer("myContainer");

//Request will be served out of the West US region
await container.ReadItemAsync<dynamic>("item", new PartitionKey("pk"))

//By using ExcludeRegions, we are able to bypass the ApplicationPreferredRegions list
// and route a request directly to the East US region
await container.ReadItemAsync<dynamic>(
  "item", 
  new PartitionKey("pk"),
  new ItemRequestOptions()
  {
    ExcludeRegions = new List<string>() { "West US", "Central US" }
  });

Use Cases

In the examples below assume we have an Azure Cosmos DB account with three regions set up: East US, Central US, and West US.

First, let’s say our application is receiving Status Code 429 responses from the backend, indicating we have exhausted all our RUs. When running into 429s, if we still want the request to succeed, we can use ExcludeRegions to ensure that the request is served out of a secondary region where there are still RUs provisioned. Today, to do this, you will need a secondary client with separate preferred regions configured. With ExcludeRegions, the process is quite simple:

ItemResponse<CosmosItem> item;

item = await container.ReadItemAsync<CosmosItem>("id", partitionKey);

if (item.StatusCode == StatusCodes.TooManyRequests)
{
    ItemRequestOptions requestOptions = new RequestOptions()
    {
        ExcludeRegions = new List<string>() { "East US" }
    };

    item = await container.ReadItemAsync<CosmosItem>("id", partitionKey, requestOptions);
}

This eliminates the need for a using secondary client and enables us to adhere to Azure Cosmos DB .NET SDK best practices by maintaining a singleton client instance. It additionally reduces the number of HTTP connections now that there is a single client. And because this works with all variations of request options the ExcludeRegions can be used for queries like in the example below:

QueryRequestOptions queryRequestOptions = new RequestOptions()
{
    ExcludeRegions = new List<string>() { "East US" }
};

using (FeedIterator<CosmosItem> queryFeedIterator = await container.GetItemQueryIterator<CosmosItem>(
    queryDefinition, 
    queryRequestOptions))
{
    while(queryFeedIterator.HasMoreResults)
    {
        var item = await feedIterator.ReadNextAsync();
    }
}

Another use case for ExcludeRegions is to ensure a request gets routed to a specific region. Suppose you need to guarantee that your requests are processed from a specific region, such as the West US. By including all your account’s regions except West US in the ExcludeRegions list, the SDK guarantees that requests are solely served there. To route a request to a specific region using the ExcludeRegions list, you can make a request like this:

ItemRequestOptions requestOptions = new RequestOptions()
{
    ExcludeRegions = new List<string>() { "East US", "Central US" }
};

ItemResponse<CosmosItem> item = await container.ReadItemAsync<CosmosItem>("id", partitionKey, requestOptions);

Next Steps

In all, the new ExcludeRegions request option is a powerful tool that allows you to have fine grain control over how your requests are routed. You can try out ExcludeRegions by updating your SDK to version 3.37.0 or above. Please share any feedback on our official GitHub repository.

About Azure Cosmos DB

Azure Cosmos DB is a fully managed and serverless distributed database for modern app development, with SLA-backed speed and availability, automatic and instant scalability, and support for open-source PostgreSQL, MongoDB, and Apache Cassandra. Try Azure Cosmos DB for free here. To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.