[How To] Cosmos DB Graph/Gremlin API: Configuring preferred read/write regions with Gremlin clients

Azure Cosmos DB’s Graph API supports turn-key geo-distribution which means that on a click of a button, one can replicate the entire graph to another Azure region. Moreover, Azure Cosmos DB being a ring-zero service one can pick a region from a large number of ever-growing Azure data centers. In a world where “apps” are becoming increasingly globalized, geo-replication provides excellent benefits like:

1. Read scalability by distributing the reads to a number of read regions.
2. Low latency by directing the users to the nearest read region.
3. Easy roll-out of a product/service to a new geographic user base, with the local data privacy laws taken care by Azure.
4. Much lower cost (both finance and time) than managing all the above by the customers themselves.

To use the geo-replication feature of Azure Cosmos DB efficiently, users need design their applications to send the right requests to the right endpoints, i.e., they need to configure the endpoints to send their requests. But before, we discuss the configuration let’s look at why such redirection is not done automatically. The primary reason is that the Gremlin clients are managed by the open-source community and are oblivious of Azure Cosmos DB specific features. Because of this, we want to send requests to a specific region of Cosmos DB, the client has to know the region-specific endpoint of Cosmos DB to send the request to, as opposed to the global endpoint (i.e., accountName.gremlin.comsmosdb.azure.com).

Of course, one can argue that the server, upon receiving the request, can discern whether the request is a read vs write request and route the request to the appropriate read/write region. While it may work, this will definitely add an additional network hop to each of client’s request, thereby increasing the latency.

Due to this limitation, it is expected that the users initialize their gremlin clients explicitly with region-specific endpoint to avoid any network delay to related to server-side redirection logic.

Now, we will see how we can construct the region-specific gremlin server endpoints. The idea is fairly simple. We get the global endpoint of the gremlin account and modify it to get the region-specific one. Once a gremlin client is initialized with these region-specific gremlin endpoints, the requests will be routed accordingly. The code snippet below demonstrates this.

One point to note here is that one may need to keep handy multiple gremlin clients each initialized with different regional endpoints, so that reads and writes could be routed accordingly.

Option 1

The easiest way to do this is to get the list of read and write regions from the overview blade of the Azure Cosmos DB account, and use the example below to construct the region specific gremlin endpoints.

The highlighted box shows the read and write region configured for an account.

Option 2

One can also do this programmatically using the following example: