Skip to content

[Read Consistency Strategy]: Implement ReadConsistencyStrategy Enum and Integration #5522

@aavasthy

Description

@aavasthy

Why needed:
Current ConsistencyLevel API only allows reducing consistency from account default. Customers get ability to perform quorum reads even with Eventual/Session account consistency to ensure reading latest data without changing RPO requirements.

Implementation Approach:
• Create new ReadConsistencyStrategy enum with values: Default, Eventual, Session, LatestCommitted, LatestCommittedWriteRegion, LatestCommittedMultiRegion, GlobalStrong
• Add property to both CosmosClientOptions/Builder and RequestOptions
• Implement behavior where RequestOption value uses client-level setting when set to Default
• Deprecate existing ConsistencyLevel API (mark as deprecated but maintain for backward compatibility)

Value Client-level RequestOption
Default Use default behavior for account's default consistency level Use the behavior defined on Client-level
Eventual Eventual consistency (single random secondary replica) Eventual consistency (single random secondary replica)
Session Use Session consistency as default Requires either an explicit session token in RequestOptions or session client-level EnableSessionTokenContainer == true. Otherwise will result in an error.
LatestCommitted Will do a quorum read – followed by GLSN barrier requests if needed in whatever region used for reads. See client-level
LatestCommittedWriteRegion Will do a quorum read in the write region (see "x-ms-cosmos-write-region-processing-only" header description below) – followed by GLSN barrier requests if needed.

NOTE: Only allowed for SM

NOTE: Documentation needs to clearly spell out side-effects on session consistency when making regular cross-region requests.
See client-level
LatestCommittedMultiRegion Only for N-region commit – not initially needed

Will do a quorum read in the write region (see "x-ms-cosmos-hub-region-processing-only" header description below) – followed by N-Region-CommitLSN ("x-ms-cosmos-global-nregion-committed-glsn") barrier requests if needed.
See client-level
  1. Strong Consistency Validation
    • Detect when account's default consistency level is less than Strong (Eventual, Session, Consistent Prefix, or Bounded Staleness)
    • Throw error if ReadConsistencyStrategy is set to GlobalStrong on such accounts
    • Error message should indicate that Strong consistency reads are only allowed on accounts with Strong as default consistency
  2. Single-Master Restriction Validation
    • Detect account configuration for single vs multi-master setup
    • Throw error if ReadConsistencyStrategy is set to LatestCommittedWriteRegion or LatestCommittedMultiRegion on multi-master accounts
    • These strategies are only meaningful in single-master where there's a clear write region
    • Error message should indicate these strategies require single-master configuration
  3. Session Token Validation
    • When request-level ReadConsistencyStrategy is Session, check:
    • If EnableSessionTokenContainer is false (or not set and account default isn't Session)
    • If no explicit session token is provided in request options
    • Throw error if both conditions are true
    • Error message should guide user to either enable session token container or provide explicit session token

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions