CosmosQueryRequestOptions Class

  • java.lang.Object
    • com.azure.cosmos.models.CosmosQueryRequestOptions

public class CosmosQueryRequestOptions

Specifies the options associated with query methods (enumeration operations) in the Azure Cosmos DB database service.

Constructor Summary

Constructor Description
CosmosQueryRequestOptions()

Instantiates a new query request options.

Method Summary

Modifier and Type Method and Description
ConsistencyLevel getConsistencyLevel()

Gets the consistency level required for the request.

DedicatedGatewayRequestOptions getDedicatedGatewayRequestOptions()

Gets the Dedicated Gateway Request Options

CosmosDiagnosticsThresholds getDiagnosticsThresholds()

Gets the diagnostic thresholds used as an override for a specific operation.

List<String> getExcludedRegions()

Gets the list of regions to exclude for the request/retries.

FeedRange getFeedRange()

Gets the FeedRange

int getMaxBufferedItemCount()

Gets the maximum number of items that can be buffered client side during parallel query execution.

int getMaxDegreeOfParallelism()

Gets the number of concurrent operations run client side during parallel query execution.

PartitionKey getPartitionKey()

Gets the partition key used to identify the current request's target partition.

int getResponseContinuationTokenLimitInKb()

Gets the ResponseContinuationTokenLimitInKb request option for item query requests in the Azure Cosmos DB service.

String getSessionToken()

Gets the session token for use with session consistency.

Duration getThresholdForDiagnosticsOnTracer()

Gets the thresholdForDiagnosticsOnTracer, if latency on query operation is greater than this diagnostics will be send to open telemetry exporter as events in tracer span of end to end CRUD api.

String getThroughputControlGroupName()

Get throughput control group name.

boolean isIndexMetricsEnabled()

Gets indexMetricsEnabled, which is used to obtain the index metrics to understand how the query engine used existing indexes and could use potential new indexes.

boolean isQueryMetricsEnabled()

Gets the option to enable populate query metrics.

Boolean isScanInQueryEnabled()

Gets the option to allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.

CosmosQueryRequestOptions setConsistencyLevel(ConsistencyLevel consistencyLevel)

Sets the consistency level required for the request.

CosmosQueryRequestOptions setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request.

CosmosQueryRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)

Sets the Dedicated Gateway Request Options

CosmosQueryRequestOptions setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds)

Allows overriding the diagnostic thresholds for a specific operation.

CosmosQueryRequestOptions setExcludedRegions(List<String> excludeRegions)

List of regions to be excluded for the request/retries.

CosmosQueryRequestOptions setFeedRange(FeedRange feedRange)

Sets the FeedRange that we want to query

CosmosQueryRequestOptions setIndexMetricsEnabled(boolean indexMetricsEnabled)

Sets indexMetricsEnabled, which is used to obtain the index metrics to understand how the query engine used existing indexes and could use potential new indexes.

CosmosQueryRequestOptions setMaxBufferedItemCount(int maxBufferedItemCount)

Sets the maximum number of items that can be buffered client side during parallel query execution.

CosmosQueryRequestOptions setMaxDegreeOfParallelism(int maxDegreeOfParallelism)

Sets the number of concurrent operations run client side during parallel query execution.

CosmosQueryRequestOptions setPartitionKey(PartitionKey partitionkey)

Sets the partition key used to identify the current request's target partition.

CosmosQueryRequestOptions setQueryMetricsEnabled(boolean queryMetricsEnabled)

Sets the option to enable/disable getting metrics relating to query execution on item query requests.

CosmosQueryRequestOptions setQueryName(String queryName)

Sets the logical query name - this identifier is only used for metrics and logs to distinguish different queries in telemetry.

CosmosQueryRequestOptions setResponseContinuationTokenLimitInKb(int limitInKb)

Sets the ResponseContinuationTokenLimitInKb request option for item query requests in the Azure Cosmos DB service.

CosmosQueryRequestOptions setScanInQueryEnabled(Boolean scanInQueryEnabled)

Sets the option to allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.

CosmosQueryRequestOptions setSessionToken(String sessionToken)

Sets the session token for use with session consistency.

CosmosQueryRequestOptions setThresholdForDiagnosticsOnTracer(Duration thresholdForDiagnosticsOnTracer)

Sets the thresholdForDiagnosticsOnTracer, if latency on query operation is greater than this diagnostics will be send to open telemetry exporter as events in tracer span of end to end CRUD api.

CosmosQueryRequestOptions setThroughputControlGroupName(String throughputControlGroupName)

Set the throughput control group name.

Methods inherited from java.lang.Object

Constructor Details

CosmosQueryRequestOptions

public CosmosQueryRequestOptions()

Instantiates a new query request options.

Method Details

getConsistencyLevel

public ConsistencyLevel getConsistencyLevel()

Gets the consistency level required for the request.

Returns:

the consistency level.

getDedicatedGatewayRequestOptions

public DedicatedGatewayRequestOptions getDedicatedGatewayRequestOptions()

Gets the Dedicated Gateway Request Options

Returns:

the Dedicated Gateway Request Options

getDiagnosticsThresholds

public CosmosDiagnosticsThresholds getDiagnosticsThresholds()

Gets the diagnostic thresholds used as an override for a specific operation. If no operation specific diagnostic threshold has been specified, this method will return null, although at runtime the default thresholds specified at the client-level will be used.

Returns:

the diagnostic thresholds used as an override for a specific operation.

getExcludedRegions

public List getExcludedRegions()

Gets the list of regions to exclude for the request/retries. These regions are excluded from the preferred region list.

Returns:

a list of excluded regions

getFeedRange

public FeedRange getFeedRange()

Gets the FeedRange

Returns:

getMaxBufferedItemCount

public int getMaxBufferedItemCount()

Gets the maximum number of items that can be buffered client side during parallel query execution.

Returns:

maximum number of items that can be buffered client side during parallel query execution.

getMaxDegreeOfParallelism

public int getMaxDegreeOfParallelism()

Gets the number of concurrent operations run client side during parallel query execution.

Returns:

number of concurrent operations run client side during parallel query execution.

getPartitionKey

public PartitionKey getPartitionKey()

Gets the partition key used to identify the current request's target partition.

Returns:

the partition key.

getResponseContinuationTokenLimitInKb

public int getResponseContinuationTokenLimitInKb()

Gets the ResponseContinuationTokenLimitInKb request option for item query requests in the Azure Cosmos DB service. If not already set returns 0.

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

Returns:

return set ResponseContinuationTokenLimitInKb, or 0 if not set

getSessionToken

public String getSessionToken()

Gets the session token for use with session consistency.

Returns:

the session token.

getThresholdForDiagnosticsOnTracer

public Duration getThresholdForDiagnosticsOnTracer()

Gets the thresholdForDiagnosticsOnTracer, if latency on query operation is greater than this diagnostics will be send to open telemetry exporter as events in tracer span of end to end CRUD api. Default is 500 ms.

Returns:

thresholdForDiagnosticsOnTracer the latency threshold for diagnostics on tracer.

getThroughputControlGroupName

public String getThroughputControlGroupName()

Get throughput control group name.

Returns:

The throughput control group name.

isIndexMetricsEnabled

public boolean isIndexMetricsEnabled()

Gets indexMetricsEnabled, which is used to obtain the index metrics to understand how the query engine used existing indexes and could use potential new indexes. The results will be displayed in QueryMetrics. Please note that this options will incurs overhead, so it should be enabled when debuging slow queries.

Returns:

indexMetricsEnabled (default: false)

isQueryMetricsEnabled

public boolean isQueryMetricsEnabled()

Gets the option to enable populate query metrics. By default query metrics are enabled.

Returns:

whether to enable populate query metrics (default: true)

isScanInQueryEnabled

public Boolean isScanInQueryEnabled()

Gets the option to allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.

Returns:

the option of enable scan in query.

setConsistencyLevel

public CosmosQueryRequestOptions setConsistencyLevel(ConsistencyLevel consistencyLevel)

Sets the consistency level required for the request. The effective consistency level can only be reduce for read/query requests. So when the Account's default consistency level is for example Session you can specify on a request-by-request level for individual requests that Eventual consistency is sufficient - which could reduce the latency and RU charges for this request but will not guarantee session consistency (read-your-own-write) anymore

Parameters:

consistencyLevel - the consistency level.

Returns:

the CosmosItemRequestOptions.

setCosmosEndToEndOperationLatencyPolicyConfig

public CosmosQueryRequestOptions setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request. If the config is already set * on the client, then this will override the client level config for this request

Parameters:

cosmosEndToEndOperationLatencyPolicyConfig - the CosmosEndToEndOperationLatencyPolicyConfig

Returns:

the CosmosQueryRequestOptions

setDedicatedGatewayRequestOptions

public CosmosQueryRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)

Sets the Dedicated Gateway Request Options

Parameters:

dedicatedGatewayRequestOptions - Dedicated Gateway Request Options

Returns:

the CosmosQueryRequestOptions

setDiagnosticsThresholds

public CosmosQueryRequestOptions setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds)

Allows overriding the diagnostic thresholds for a specific operation.

Parameters:

operationSpecificThresholds - the diagnostic threshold override for this operation

Returns:

the CosmosQueryRequestOptions.

setExcludedRegions

public CosmosQueryRequestOptions setExcludedRegions(List excludeRegions)

List of regions to be excluded for the request/retries. Example "East US" or "East US, West US" These regions will be excluded from the preferred regions list

Parameters:

excludeRegions - the regions to exclude

Returns:

setFeedRange

public CosmosQueryRequestOptions setFeedRange(FeedRange feedRange)

Sets the FeedRange that we want to query

Parameters:

feedRange - the FeedRange

Returns:

the CosmosQueryRequestOptions.

setIndexMetricsEnabled

public CosmosQueryRequestOptions setIndexMetricsEnabled(boolean indexMetricsEnabled)

Sets indexMetricsEnabled, which is used to obtain the index metrics to understand how the query engine used existing indexes and could use potential new indexes. The results will be displayed in QueryMetrics. Please note that this options will incurs overhead, so it should be enabled when debugging slow queries. By default the indexMetrics are disabled.

Parameters:

indexMetricsEnabled - a boolean used to obtain the index metrics

Returns:

indexMetricsEnabled

setMaxBufferedItemCount

public CosmosQueryRequestOptions setMaxBufferedItemCount(int maxBufferedItemCount)

Sets the maximum number of items that can be buffered client side during parallel query execution.

Parameters:

maxBufferedItemCount - maximum number of items.

Returns:

the CosmosQueryRequestOptions.

setMaxDegreeOfParallelism

public CosmosQueryRequestOptions setMaxDegreeOfParallelism(int maxDegreeOfParallelism)

Sets the number of concurrent operations run client side during parallel query execution.

Parameters:

maxDegreeOfParallelism - number of concurrent operations.

Returns:

the CosmosQueryRequestOptions.

setPartitionKey

public CosmosQueryRequestOptions setPartitionKey(PartitionKey partitionkey)

Sets the partition key used to identify the current request's target partition.

Parameters:

partitionkey - the partition key value.

Returns:

the CosmosQueryRequestOptions.

setQueryMetricsEnabled

public CosmosQueryRequestOptions setQueryMetricsEnabled(boolean queryMetricsEnabled)

Sets the option to enable/disable getting metrics relating to query execution on item query requests. By default query metrics are enabled.

Parameters:

queryMetricsEnabled - whether to enable or disable query metrics

Returns:

the CosmosQueryRequestOptions.

setQueryName

public CosmosQueryRequestOptions setQueryName(String queryName)

Sets the logical query name - this identifier is only used for metrics and logs to distinguish different queries in telemetry. Cardinality of unique values for queryName should be reasonably low - like significantly smaller than 100.

Parameters:

queryName - a logical query name to distinguish this query pattern from others

Returns:

the logical query name

setResponseContinuationTokenLimitInKb

public CosmosQueryRequestOptions setResponseContinuationTokenLimitInKb(int limitInKb)

Sets the ResponseContinuationTokenLimitInKb request option for item query requests in the Azure Cosmos DB service.

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

The continuation token contains both required and optional fields. The required fields are necessary for resuming the execution from where it was stooped. The optional fields may contain serialized index lookup work that was done but not yet utilized. This avoids redoing the work again in subsequent continuations and hence improve the query performance. Setting the maximum continuation size to 1KB, the Azure Cosmos DB service will only serialize required fields. Starting from 2KB, the Azure Cosmos DB service would serialize as much as it could fit till it reaches the maximum specified size.

Parameters:

limitInKb - continuation token size limit.

Returns:

the CosmosQueryRequestOptions.

setScanInQueryEnabled

public CosmosQueryRequestOptions setScanInQueryEnabled(Boolean scanInQueryEnabled)

Sets the option to allow scan on the queries which couldn't be served as indexing was opted out on the requested paths.

Parameters:

scanInQueryEnabled - the option of enable scan in query.

Returns:

the CosmosQueryRequestOptions.

setSessionToken

public CosmosQueryRequestOptions setSessionToken(String sessionToken)

Sets the session token for use with session consistency.

Parameters:

sessionToken - the session token.

Returns:

the CosmosQueryRequestOptions.

setThresholdForDiagnosticsOnTracer

public CosmosQueryRequestOptions setThresholdForDiagnosticsOnTracer(Duration thresholdForDiagnosticsOnTracer)

Sets the thresholdForDiagnosticsOnTracer, if latency on query operation is greater than this diagnostics will be send to open telemetry exporter as events in tracer span of end to end CRUD api. Default is 500 ms

Parameters:

thresholdForDiagnosticsOnTracer - the latency threshold for diagnostics on tracer.

Returns:

the CosmosQueryRequestOptions

setThroughputControlGroupName

public CosmosQueryRequestOptions setThroughputControlGroupName(String throughputControlGroupName)

Set the throughput control group name.

Parameters:

throughputControlGroupName - The throughput control group name.

Returns:

Applies to