CosmosReadManyRequestOptions Class

Package:

com.azure.cosmos.models

Maven Artifact:

com.azure:azure-cosmos:4.80.0

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

public final class CosmosReadManyRequestOptions

Specifies the options associated with read many operation in the Azure Cosmos DB database service.

Constructor Summary

Constructor	Description
CosmosReadManyRequestOptions()	Instantiates a new read many request options.

Method Summary

Modifier and Type	Method and Description
Map<CosmosAdditionalHeaderName,String>	getAdditionalHeaders() Gets the additional headers configured on this request options instance.
ConsistencyLevel	getConsistencyLevel() Gets the consistency level required for the request.
CosmosItemSerializer	getCustomItemSerializer() Gets the custom item serializer defined for this instance of request options
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.
Set<String>	getKeywordIdentifiers() Gets the custom ids.
ReadConsistencyStrategy	getReadConsistencyStrategy() Gets the read consistency strategy for the request.
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.
CosmosReadManyRequestOptions	setAdditionalHeaders(Map<CosmosAdditionalHeaderName,String> additionalHeaders) Sets additional headers to be included with this specific request.
CosmosReadManyRequestOptions	setConsistencyLevel(ConsistencyLevel consistencyLevel) Sets the consistency level required for the request.
CosmosReadManyRequestOptions	setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig) Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request.
CosmosReadManyRequestOptions	setCustomItemSerializer(CosmosItemSerializer customItemSerializer) Allows specifying a custom item serializer to be used for this operation.
CosmosReadManyRequestOptions	setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions) Sets the Dedicated Gateway Request Options
CosmosReadManyRequestOptions	setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds) Allows overriding the diagnostic thresholds for a specific operation.
CosmosReadManyRequestOptions	setExcludedRegions(List<String> excludeRegions) List of regions to be excluded for the request/retries.
CosmosReadManyRequestOptions	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.
CosmosReadManyRequestOptions	setKeywordIdentifiers(Set<String> keywordIdentifiers) Sets the custom ids.
CosmosReadManyRequestOptions	setQueryMetricsEnabled(boolean queryMetricsEnabled) Sets the option to enable/disable getting metrics relating to query execution on item query requests.
CosmosReadManyRequestOptions	setReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy) Sets the read consistency strategy required for the request.
CosmosReadManyRequestOptions	setResponseContinuationTokenLimitInKb(int limitInKb) Sets the ResponseContinuationTokenLimitInKb request option for item query requests in the Azure Cosmos DB service.
CosmosReadManyRequestOptions	setSessionToken(String sessionToken) Sets the session token for use with session consistency.
CosmosReadManyRequestOptions	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.
CosmosReadManyRequestOptions	setThroughputControlGroupName(String throughputControlGroupName) Set the throughput control group name.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Details

CosmosReadManyRequestOptions

public CosmosReadManyRequestOptions()

Instantiates a new read many request options.

Method Details

getAdditionalHeaders

public Map<CosmosAdditionalHeaderName,String> getAdditionalHeaders()

Gets the additional headers configured on this request options instance.

Returns:

unmodifiable map of additional headers, or null if none are set

getConsistencyLevel

public ConsistencyLevel getConsistencyLevel()

Gets the consistency level required for the request.

Returns:

the consistency level.

getCustomItemSerializer

public CosmosItemSerializer getCustomItemSerializer()

Gets the custom item serializer defined for this instance of request options

Returns:

the custom item serializer

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<String> 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

getKeywordIdentifiers

public Set<String> getKeywordIdentifiers()

Gets the custom ids.

Returns:

the custom ids.

getReadConsistencyStrategy

public ReadConsistencyStrategy getReadConsistencyStrategy()

Gets the read consistency strategy for the request.

Returns:

the read consistency strategy.

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)

setAdditionalHeaders

public CosmosReadManyRequestOptions setAdditionalHeaders(Map<CosmosAdditionalHeaderName,String> additionalHeaders)

Sets additional headers to be included with this specific request.

The CosmosAdditionalHeaderName class defines exactly which headers are supported. This allows per-request header customization, such as setting a workload ID that overrides the client-level default set via com.azure.cosmos.CosmosClientBuilder#additionalHeaders(java.util.Map).

If the same header is also set at the client level, the request-level value takes precedence.

Note: This method uses additive (merge) semantics — headers from multiple calls are merged into the existing set. Passing null or an empty map does not clear previously set headers. To reset headers, create a new options instance.

Parameters:

additionalHeaders - map of CosmosAdditionalHeaderName to value

Returns:

the CosmosReadManyRequestOptions.

setConsistencyLevel

public CosmosReadManyRequestOptions 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 CosmosReadManyRequestOptions.

setCosmosEndToEndOperationLatencyPolicyConfig

public CosmosReadManyRequestOptions 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 CosmosReadManyRequestOptions

setCustomItemSerializer

public CosmosReadManyRequestOptions setCustomItemSerializer(CosmosItemSerializer customItemSerializer)

Allows specifying a custom item serializer to be used for this operation. If the serializer on the request options is null, the serializer on CosmosClientBuilder is used. If both serializers are null (the default), an internal Jackson ObjectMapper is ued for serialization/deserialization.

Parameters:

customItemSerializer - the custom item serializer for this operation

Returns:

the CosmosItemRequestOptions.

setDedicatedGatewayRequestOptions

public CosmosReadManyRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)

Sets the Dedicated Gateway Request Options

Parameters:

dedicatedGatewayRequestOptions - Dedicated Gateway Request Options

Returns:

the CosmosReadManyRequestOptions

setDiagnosticsThresholds

public CosmosReadManyRequestOptions setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds)

Allows overriding the diagnostic thresholds for a specific operation.

Parameters:

operationSpecificThresholds - the diagnostic threshold override for this operation

Returns:

the CosmosReadManyRequestOptions.

setExcludedRegions

public CosmosReadManyRequestOptions setExcludedRegions(List<String> 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. If all the regions are excluded, the request will be sent to the primary region for the account. The primary region is the write region in a single master account and the hub region in a multi-master account.

Parameters:

excludeRegions - the regions to exclude

Returns:

the CosmosReadManyRequestOptions

setIndexMetricsEnabled

public CosmosReadManyRequestOptions 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

setKeywordIdentifiers

public CosmosReadManyRequestOptions setKeywordIdentifiers(Set<String> keywordIdentifiers)

Sets the custom ids.

Parameters:

keywordIdentifiers - the custom ids.

Returns:

the current request options.

setQueryMetricsEnabled

public CosmosReadManyRequestOptions 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 CosmosReadManyRequestOptions.

setReadConsistencyStrategy

public CosmosReadManyRequestOptions setReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy)

Sets the read consistency strategy required for the request. This allows specifying the effective consistency strategy for read/query operations and even request stronger consistency (`LOCAL_COMMITTED` for example) for accounts with lower default consistency level NOTE: If the read consistency strategy set on a request level here is `SESSION` and the default consistency level specified when constructing the CosmosClient instance via CosmosClientBuilder.consistencyLevel is not SESSION then session token capturing also needs to be enabled by calling CosmosClientBuilder:sessionCapturingOverrideEnabled(true) explicitly. NOTE: The `setConsistencyLevel` value specified is ignored when `setReadConsistencyStrategy` is used unless `DEFAULT` is specified.

Parameters:

readConsistencyStrategy - the consistency level.

Returns:

the CosmosReadManyRequestOptions.

setResponseContinuationTokenLimitInKb

public CosmosReadManyRequestOptions 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 CosmosReadManyRequestOptions.

setSessionToken

public CosmosReadManyRequestOptions setSessionToken(String sessionToken)

Sets the session token for use with session consistency.

Parameters:

sessionToken - the session token.

Returns:

the CosmosReadManyRequestOptions.

setThresholdForDiagnosticsOnTracer

public CosmosReadManyRequestOptions 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 CosmosReadManyRequestOptions

setThroughputControlGroupName

public CosmosReadManyRequestOptions setThroughputControlGroupName(String throughputControlGroupName)

Set the throughput control group name.

Parameters:

throughputControlGroupName - The throughput control group name.

Returns:

A CosmosReadManyRequestOptions.