Table of Contents

Class QueryRequestOptions

Namespace
Microsoft.Azure.Cosmos
Assembly
Microsoft.Azure.Cosmos.Client.dll

The Cosmos query request options

public class QueryRequestOptions : RequestOptions
Inheritance
QueryRequestOptions
Inherited Members
Extension Methods

Constructors

QueryRequestOptions() 

public QueryRequestOptions()

Properties

ConsistencyLevel

Gets or sets the consistency level required for the request in the Azure Cosmos DB service.

public ConsistencyLevel? ConsistencyLevel { get; set; }

Property Value

ConsistencyLevel?

The consistency level required for the request.

Remarks

Azure Cosmos DB offers 5 different consistency levels. Strong, Bounded Staleness, Session, Consistent Prefix and Eventual - in order of strongest to weakest consistency. ConnectionPolicy

While this is set at a database account level, Azure Cosmos DB allows a developer to override the default consistency level for each individual request.

DedicatedGatewayRequestOptions

Gets or sets the DedicatedGatewayRequestOptions for requests against the dedicated gateway. Learn more about dedicated gateway here. These options are only exercised when ConnectionMode is set to ConnectionMode.Gateway and the dedicated gateway endpoint is used for sending requests. These options have no effect otherwise.

public DedicatedGatewayRequestOptions DedicatedGatewayRequestOptions { get; set; }

Property Value

DedicatedGatewayRequestOptions

EnableLowPrecisionOrderBy

Gets or sets the option to enable low precision order by in the Azure Cosmos DB service.

public bool? EnableLowPrecisionOrderBy { get; set; }

Property Value

bool?

The option to enable low-precision order by.

EnableOptimisticDirectExecution

Gets or sets the option for customers to opt in for direct (optimistic) execution of the query.

public bool EnableOptimisticDirectExecution { get; set; }

Property Value

bool

Direct (optimistic) execution offers improved performance for several kinds of queries such as a single partition streaming query.

EnableScanInQuery

Gets or sets the option to enable scans on the queries which couldn't be served as indexing was opted out on the requested paths in the Azure Cosmos DB service.

public bool? EnableScanInQuery { get; set; }

Property Value

bool?

Option is true if scan on queries is enabled; otherwise, false.

MaxBufferedItemCount

Gets or sets the maximum number of items that can be buffered client side during parallel query execution in the Azure Cosmos DB service. A positive property value limits the number of buffered items to the set value. If it is set to less than 0, the system automatically decides the number of items to buffer.

public int? MaxBufferedItemCount { get; set; }

Property Value

int?

The maximum count of items that can be buffered during parallel query execution.

Remarks

This is only suggestive and cannot be abided by in certain cases.

MaxConcurrency

Gets or sets the number of concurrent operations run client side during parallel query execution in the Azure Cosmos DB service. A positive property value limits the number of concurrent operations to the set value. If it is set to less than 0, the system automatically decides the number of concurrent operations to run.

public int? MaxConcurrency { get; set; }

Property Value

int?

The maximum number of concurrent operations during parallel execution. Defaults will be executed serially with no-parallelism

MaxItemCount

Gets or sets the maximum number of items to be returned in the enumeration operation in the Azure Cosmos DB service.

public int? MaxItemCount { get; set; }

Property Value

int?

The maximum number of items to be returned in the enumeration operation.

Remarks

Used for query pagination. '-1' Used for dynamic page size. This is a maximum. Query can return 0 items in the page.

PartitionKey

Gets or sets the PartitionKey for the current request in the Azure Cosmos DB service.

public PartitionKey? PartitionKey { get; set; }

Property Value

PartitionKey?

Remarks

Only applicable to Item operations

PopulateIndexMetrics

Gets or sets the PopulateIndexMetrics request option for document query requests in the Azure Cosmos DB service.

public bool? PopulateIndexMetrics { get; set; }

Property Value

bool?

Remarks

PopulateIndexMetrics is used to obtain the index metrics to understand how the query engine used existing indexes and how it could use potential new indexes. The results will be displayed in FeedResponse.IndexMetrics. Please note that this options will incur overhead, so it should be enabled only when debugging slow queries.

ResponseContinuationTokenLimitInKb

Gets or sets the ResponseContinuationTokenLimitInKb request option for document query requests in the Azure Cosmos DB service.

public int? ResponseContinuationTokenLimitInKb { get; set; }

Property Value

int?

Remarks

ResponseContinuationTokenLimitInKb is used to limit the length of continuation token in the query response. Valid values are >= 0.

SessionToken

Gets or sets the token for use with session consistency in the Azure Cosmos DB service.

public string SessionToken { get; set; }

Property Value

string

The token for use with session consistency.

Remarks

One of the ConsistencyLevel for Azure Cosmos DB is Session. In fact, this is the default level applied to accounts.

When working with Session consistency, each new write request to Azure Cosmos DB is assigned a new SessionToken. The CosmosClient will use this token internally with each read/query request to ensure that the set consistency level is maintained.

In some scenarios you need to manage this Session yourself; Consider a web application with multiple nodes, each node will have its own instance of CosmosClient If you wanted these nodes to participate in the same session (to be able read your own writes consistently across web tiers) you would have to send the SessionToken from FeedResponse<T> of the write action on one node to the client tier, using a cookie or some other mechanism, and have that token flow back to the web tier for subsequent reads. If you are using a round-robin load balancer which does not maintain session affinity between requests, such as the Azure Load Balancer, the read could potentially land on a different node to the write request, where the session was created.

If you do not flow the Azure Cosmos DB SessionToken across as described above you could end up with inconsistent read results for a period of time.