{"id":8444,"date":"2024-08-12T06:34:06","date_gmt":"2024-08-12T13:34:06","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=8444"},"modified":"2024-08-12T06:34:06","modified_gmt":"2024-08-12T13:34:06","slug":"new-sdk-options-for-fine-grained-request-routing-to-azure-cosmos-db","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/new-sdk-options-for-fine-grained-request-routing-to-azure-cosmos-db\/","title":{"rendered":"New SDK Options for Fine-Grained Request Routing to Azure Cosmos DB"},"content":{"rendered":"

\"New<\/a><\/p>\n

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<\/span> 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.<\/p>\n

What is ExcludeRegions?<\/h2>\n

ExcludeRegions<\/span> 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<\/span> property of the\u00a0RequestOptions\u00a0<\/a><\/span>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.<\/p>\n

Currently, the SDK has the ApplicationPreferredRegions<\/a> <\/span>list in the CosmosClientOptions<\/span>. 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<\/span> option allows you to bypass the order of this list on a per-request level and should be used in conjunction to PreferredLocations<\/span> to help route your requests. In the example below, we show how to create a CosmosClient<\/span> instance that uses ApplicationPreferredRegions<\/span> and how to bypass that list using the ExcludeRegions<\/span> option:<\/p>\n

CosmosClientOptions clientOptions = new CosmosClientOPtions()\r\n{\r\n  ApplicationPreferredRegions = new List<string> {\"West US\", \"Central US\", \"East US\"};\r\n}\r\n\r\nCosmosClient client = new CosmosClient(connectionString, clientOptions);\r\n\r\nDatabase db = client.GetDatabase(\"myDb\");\r\nContainer container = db.GetContainer(\"myContainer\");\r\n\r\n\/\/Request will be served out of the West US region\r\nawait container.ReadItemAsync<dynamic>(\"item\", new PartitionKey(\"pk\"))\r\n\r\n\/\/By using ExcludeRegions, we are able to bypass the ApplicationPreferredRegions list\r\n\/\/ and route a request directly to the East US region\r\nawait container.ReadItemAsync<dynamic>(\r\n  \"item\", \r\n  new PartitionKey(\"pk\"),\r\n  new ItemRequestOptions()\r\n  {\r\n    ExcludeRegions = new List<string>() { \"West US\", \"Central US\" }\r\n  });<\/code><\/pre>\n
 <\/p>\n
Use Cases<\/h2>\n
In the examples below assume we have an Azure Cosmos DB account with three regions set up: East US, Central US, and West US.<\/p>\n
\"A<\/p>\n
First, <\/a>let\u2019s say our application is receiving Status Code 429 responses from the backend, indicating we have exhausted all our <\/a>RUs. When running into <\/a>429s, if we still want the request to succeed, we can use ExcludeRegions<\/span> 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:<\/p>\n
ItemResponse<CosmosItem> item;\r\n\r\nitem = await container.ReadItemAsync<CosmosItem>(\"id\", partitionKey);\r\n\r\nif (item.StatusCode == StatusCodes.TooManyRequests)\r\n{\r\n    ItemRequestOptions requestOptions = new RequestOptions()\r\n    {\r\n        ExcludeRegions = new List<string>() { \"East US\" }\r\n    };\r\n\r\n    item = await container.ReadItemAsync<CosmosItem>(\"id\", partitionKey, requestOptions);\r\n}<\/code><\/pre>\n
 <\/p>\n
This eliminates the need for a using secondary client and enables us to adhere to Azure Cosmos DB .NET SDK best practices<\/a> by maintaining a singleton client instance. It additionally reduces the number of <\/a>HTTP connections now that there is a single client. And because this works with all variations of request options the ExcludeRegions<\/span> can be used for queries like in the example below:<\/p>\n
QueryRequestOptions queryRequestOptions = new RequestOptions()\r\n{\r\n    ExcludeRegions = new List<string>() { \"East US\" }\r\n};\r\n\r\nusing (FeedIterator<CosmosItem> queryFeedIterator = await container.GetItemQueryIterator<CosmosItem>(\r\n    queryDefinition, \r\n    queryRequestOptions))\r\n{\r\n    while(queryFeedIterator.HasMoreResults)\r\n    {\r\n        var item = await feedIterator.ReadNextAsync();\r\n    }\r\n}<\/code><\/pre>\n
 <\/p>\n
Another use case for ExcludeRegions<\/span> 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<\/span> list, the SDK guarantees that requests are solely served there. To route a request to a specific region using the ExcludeRegions<\/span> list, you can make a request like this:<\/p>\n
ItemRequestOptions requestOptions = new RequestOptions()\r\n{\r\n    ExcludeRegions = new List<string>() { \"East US\", \"Central US\" }\r\n};\r\n\r\nItemResponse<CosmosItem> item = await container.ReadItemAsync<CosmosItem>(\"id\", partitionKey, requestOptions);<\/code><\/pre>\n
 <\/p>\n
Next Steps<\/h2>\n
In all, the new ExcludeRegions<\/span> 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<\/span> by updating your SDK to version 3.37.0 or above. Please share any feedback on <\/a>our official GitHub repository.<\/a><\/p>\n
About Azure Cosmos DB<\/h2>\n
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.<\/a> To stay in the loop on Azure Cosmos DB updates, follow us on X<\/a>, YouTube<\/a>, and LinkedIn<\/a>.<\/p>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
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 […]<\/p>\n","protected":false},"author":164043,"featured_media":8456,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[14],"tags":[],"class_list":["post-8444","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-core-sql-api"],"acf":[],"blog_post_summary":"
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 […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/8444","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/164043"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=8444"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/8444\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/8456"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=8444"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=8444"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=8444"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}