Set up Azure Cosmos DB global distribution using the Table API

This article covers the following tasks:

  • Configure global distribution using the Azure portal
  • Configure global distribution using the Table API

Add global database regions using the Azure portal

Azure Cosmos DB is available in all Azure regions worldwide. After selecting the default consistency level for your database account, you can associate one or more regions (depending on your choice of default consistency level and global distribution needs).

  1. In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. In the Azure Cosmos DB page, select the database account to modify.

  3. In the account page, click Replicate data globally from the menu.

  4. In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    Click the regions in the map to add or remove them

Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. You can use this option to test the failover process or change the primary write region. Once you add a third region, the Failover Priorities option is enabled on the same page so that you can change the failover order for reads.

Selecting global database regions

There are two common scenarios for configuring two or more regions:

  1. Delivering low-latency access to data to end users no matter where they are located around the globe
  2. Adding regional resiliency for business continuity and disaster recovery (BCDR)

For delivering low-latency to end users, it is recommended that you deploy both the application and Azure Cosmos DB in the regions that correspond to where the application's users are located.

For BCDR, it is recommended to add regions based on the region pairs described in the Business continuity and disaster recovery (BCDR): Azure Paired Regions article.

Connecting to a preferred region using the Table API

In order to take advantage of global distribution, client applications can specify the ordered preference list of regions to be used to perform document operations. This can be done by setting the TableConnectionPolicy.PreferredLocations property. The Azure Cosmos DB Table API SDK picks the best endpoint to communicate with based on the account configuration, current regional availability and the supplied preference list.

The PreferredLocations should contain a comma-separated list of preferred (multi-homing) locations for reads. Each client instance can specify a subset of these regions in the preferred order for low latency reads. The regions must be named using their display names, for example, West US.

All reads are sent to the first available region in the PreferredLocations list. If the request fails, the client will fail down the list to the next region, and so on.

The SDK attempts to read from the regions specified in PreferredLocations. So, for example, if the Database Account is available in three regions, but the client only specifies two of the non-write regions for PreferredLocations, then no reads will be served out of the write region, even in the case of failover.

The SDK automatically sends all writes to the current write region.

If the PreferredLocations property is not set, all requests will be served from the current write region.

That's it, that completes this tutorial. You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in Azure Cosmos DB. And for more information about how global database replication works in Azure Cosmos DB, see Distribute data globally with Azure Cosmos DB.

Next steps

In this tutorial, you've done the following:

  • Configure global distribution using the Azure portal
  • Configure global distribution using the Azure Cosmos DB Table APIs