Consistency levels in DocumentDB
Azure DocumentDB is designed from the ground up with global distribution in mind. It is designed to offer predictable low latency guarantees, a 99.99% availability SLA, and multiple well-defined relaxed consistency models. Currently, DocumentDB provides four consistency levels: strong, bounded-staleness, session, and eventual. Besides the strong and the eventual consistency models commonly offered by other NoSQL databases, DocumentDB also offers two carefully codified and operationalized consistency models – bounded staleness and session, and has validated their usefulness against real world use cases. Collectively these four consistency levels enable you to make well-reasoned trade-offs between consistency, availability, and latency.
Scope of consistency
You can configure a default consistency level on your database account that applies to all the collections (across all of the databases) under your database account. By default, all reads and queries issued against the user defined resources will use the default consistency level specified on the database account. However, you can relax the consistency level of a specific read/query request by specifying the [x-ms-consistency-level] request header. There are four types of consistency levels supported by the DocumentDB replication protocol that provide a clear trade-off between specific consistency guarantees and performance, as described below.
- Strong consistency offers a linearizability guarantee with the reads guaranteed to return the most recent version of a document.
- Strong consistency guarantees that a write is only visible after it is committed durably by the majority quorum of replicas. A write is either synchronously committed durably by both the primary and the quorum of secondaries, or it is aborted. A read is always acknowledged by the majority read quorum, a client can never see an uncommitted or partial write and is always guaranteed to read the latest acknowledged write.
- DocumentDB accounts that are configured to use strong consistency cannot associate more than one Azure region with their DocumentDB account.
- The cost of a read operation (in terms of request units consumed) with strong consistency is higher than session and eventual, but the same as bounded staleness.
- Bounded staleness consistency guarantees that the reads may lag behind writes by at most K versions or prefixes of a document or t time-interval.
- Consequently, when choosing bounded staleness, the “staleness” can be configured in two ways:
- Number of versions K of the document by which the reads lag behind the writes
- Time interval t
- Bounded staleness offers total global order except within the “staleness window”. Note that the monotonic read guarantees exists within a region both inside and outside the “staleness window”.
- Bounded staleness provides a stronger consistency guarantee than session or eventual consistency. For globally distributed applications, we recommend you use bounded staleness for scenarios where you would like to have strong consistency but also want 99.99% availability and low latency.
- DocumentDB accounts that are configured with bounded staleness consistency can associate any number of Azure regions with their DocumentDB account.
- The cost of a read operation (in terms of RUs consumed) with bounded staleness is higher than session and eventual consistency, but the same as strong consistency.
- Unlike the global consistency models offered by strong and bounded staleness consistency levels, session consistency is scoped to a client session.
- Session consistency is ideal for all scenarios where a device or user session is involved since it guarantees monotonic reads, monotonic writes, and read your own writes (RYW) guarantees.
- Session consistency provides predictable consistency for a session, and maximum read throughput while offering the lowest latency writes and reads.
- DocumentDB accounts that are configured with session consistency can associate any number of Azure regions with their DocumentDB account.
- The cost of a read operation (in terms of RUs consumed) with session consistency level is less than strong and bounded staleness, but more than eventual consistency
- Eventual consistency guarantees that in absence of any further writes, the replicas within the group will eventually converge.
- Eventual consistency is the weakest form of consistency where a client may get the values that are older than the ones it had seen before.
- Eventual consistency provides the weakest read consistency but offers the lowest latency for both reads and writes.
- DocumentDB accounts that are configured with eventual consistency can associate any number of Azure regions with their DocumentDB account.
- The cost of a read operation (in terms of RUs consumed) with the eventual consistency level is the lowest of all the DocumentDB consistency levels.
The following table captures various consistency guarantees corresponding to the four consistency levels.
|Total global order||Yes||Yes, outside of the “staleness window”||No, partial “session” order||No|
|Consistent prefix guarantee||Yes||Yes||Yes||Yes|
|Monotonic reads||Yes||Yes, across regions outside of the staleness window and within a region all the time.||Yes, for the given session||No|
|Read your writes||Yes||Yes||Yes (in the write region)||No|
Configuring the default consistency level
- In the Azure portal, in the Jumpbar, click DocumentDB (NoSQL).
- In the DocumentDB (NoSQL) blade, select the database account to modify.
- In the account blade, click Default consistency.
In the Default Consistency blade, select the new consistency level and click Save.
Configuring the default consistency level is not supported within the Azure DocumentDB Emulator.
Consistency levels for queries
By default, for user defined resources, the consistency level for queries is the same as the consistency level for reads. By default, the index is updated synchronously on each insert, replace, or delete of a document to the collection. This enables the queries to honor the same consistency level as that of the document reads. While DocumentDB is write optimized and supports sustained volumes of document writes, synchronous index maintenance and serving consistent queries, you can configure certain collections to update their index lazily. Lazy indexing further boosts the write performance and is ideal for bulk ingestion scenarios when a workload is primarily read-heavy.
|Consistent (default)||Select from strong, bounded staleness, session, or eventual||Select from strong, bounded staleness, session, or eventual|
|Lazy||Select from strong, bounded staleness, session, or eventual||Eventual|
|None||Select from strong, bounded staleness, session, or eventual||Not applicable|
As with read requests, you can lower the consistency level of a specific query request by specifying the x-ms-consistency-level request header.
If you'd like to do more reading about consistency levels and tradeoffs, we recommend the following resources:
- Doug Terry. Replicated Data Consistency explained through baseball (video).
- Doug Terry. Replicated Data Consistency explained through baseball.
- Doug Terry. Session Guarantees for Weakly Consistent Replicated Data.
- Daniel Abadi. Consistency Tradeoffs in Modern Distributed Database Systems Design: CAP is only part of the story”.
- Peter Bailis, Shivaram Venkataraman, Michael J. Franklin, Joseph M. Hellerstein, Ion Stoica. Probabilistic Bounded Staleness (PBS) for Practical Partial Quorums.
- Werner Vogels. Eventual Consistent - Revisited.