HPK: Add internal CosmosClientOptions flag UseLengthAwareRangeComparer for length aware range comparer rollout.

[ananth7592]

Description

This change adds an internal-only CosmosClientOptions.UseLengthAwareRangeComparer property to enable controlled rollout of the HPK EPK range comparator fix. This is useful for both V3 and compute gateway rollout control.

Background:
The HPK EPK normalization fix (released in V3 Preview 3.56.0-preview.0) currently uses an environment variable feature flag (default=True). However, Compute doesn't support environment variables - it only supports TenantConfigurationProvider and CosmosClientOptions for feature flag control.

This Change:

• Adds internal bool UseLengthAwareRangeComparer to CosmosClientOptions (default=true)
• Threads the parameter through the entire query pipeline to QueryRangeUtils
• Updates all test call sites to explicitly pass useLengthAwareRangeComparer: true
• No public API surface changes (internal-only property)

Type of change

• No public API surface changes (internal-only property)

Closing issues

To automatically close an issue: closes #IssueNumber

[github-actions]

Please follow the required format: "[Internal] Category: (Adds|Fixes|Refactors|Removes) Description"

Internal should be used for PRs that have no customer impact. This flag is used to help generate the changelog to know which PRs should be included. Examples:
Diagnostics: Adds GetElapsedClientLatency to CosmosDiagnostics
PartitionKey: Fixes null reference when using default(PartitionKey)
[v4] Client Encryption: Refactors code to external project
[Internal] Query: Adds code generator for CosmosNumbers for easy additions in the future.

[Copilot]

Pull request overview

This pull request adds an internal CosmosClientOptions.UseLengthAwareRangeComparer flag to enable controlled rollout of the HPK EPK range comparator fix. The change threads this boolean parameter through the entire query pipeline from CosmosClientOptions down to QueryRangeUtils and CollectionRoutingMap, where it controls whether to use length-aware or legacy range comparers for EPK range comparisons.

Changes:

• Added internal UseLengthAwareRangeComparer property to CosmosClientOptions (default=true)
• Threaded the parameter through DocumentClient, ClientContextCore, PartitionKeyRangeCache, CollectionRoutingMap, and the entire query pipeline
• Updated all test call sites to pass the new parameter explicitly

Reviewed changes

Copilot reviewed 46 out of 46 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
CosmosClientOptions.cs	Added internal property UseLengthAwareRangeComparer with documentation
DocumentClient.cs	Added parameter to constructor and passed to PartitionKeyRangeCache
ClientContextCore.cs	Threaded parameter from client options to DocumentClient
PartitionKeyRangeCache.cs	Added parameter to constructor and used in TryCombine calls
CollectionRoutingMap.cs	Updated constructor and methods to accept and use the parameter
QueryRangeUtils.cs	Added parameter to methods for comparator selection
Query/v3Query/QueryIterator.cs	Passed parameter from client options to query context
Query/v3Query/CosmosQueryClientCore.cs	Passed parameter to QueryRangeUtils
Query pipeline files	Threaded parameter through all pipeline stages
Test files (various)	Updated mock constructors and test call sites with new parameter

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.