Session Consistency and the .NET Client SDK

Question

I am trying to understand what Sessions Consistency actually means when working with Azure DocumentDb via the .NET client SDK i.e. What defines (and bounds) a session. Is a new session created each time we create a new instance of DocumentClient and if so does the behavior change if we are using the IReliableReadWriteDocumentClient wrapper?

Answer 1

Yes, a new session is created each time you create a new instance of the DocumentClient class. Each DocumentClient instance maintains a map of collection -> session token mapping. The client saves the latest session token received from the server, and echoes it as a header (x-ms-sessiontoken) during read requests. This enables DocumentDB to locate an up-to-date replica of your collection to serve session (or read-your-writes) consistency. This is the same with IReliableReadWriteDocumentClient, since it's a wrapper over the DocumentClient.

Note: the easiest way to achieve session consistency is to have a single DocumentClient instance manage it for you automatically. You can also manage a logical session across multiple DocumentClient instances with a little more complexity. For example, let's say that you have a load balanced Web API with two servers each with a DocumentClient instance, and you want session consistency across these servers.

1. client writes -> App Server 1 -> DocumentDB
2. client reads -> App Server 2 -> DocumentDB

You can implement this by saving the x-ms-sessiontoken returned in step 1 by saving it as a cookie in the client, then echoing that x-ms-sessiontoken in the read request. By round-tripping the session token, you can get session consistency.