CosmosReadManyByPartitionKeysRequestOptions Class

Package:

com.azure.cosmos.models

Maven Artifact:

com.azure:azure-cosmos:4.80.0

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

public final class CosmosReadManyByPartitionKeysRequestOptions

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

This is distinct from CosmosReadManyRequestOptions (used by the readMany(List<CosmosItemIdentity>) API). It exposes only the knobs that are applicable to readManyByPartitionKeys — for example, properties that influence query parallelism inside a single physical partition or a feed range filter are intentionally not exposed because the operation is fully managed by the SDK.

Constructor Summary

Constructor	Description
CosmosReadManyByPartitionKeysRequestOptions()	Instantiates a new readManyByPartitionKeys request options.

Method Summary

Modifier and Type	Method and Description
Map<CosmosAdditionalHeaderName,String>	getAdditionalHeaders() Gets the additional headers configured on this request options instance.
String	getContinuationToken() Gets the composite continuation token used to resume a previous readManyByPartitionKeys invocation.
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 keyword identifiers.
int	getMaxBackendContinuationTokenSizeInKb() Gets the maximum size (in kilobytes) of the backend continuation token embedded inside the composite readManyByPartitionKeys continuation token.
Integer	getMaxBatchSize() Gets the maximum number of partition key values per batch query sent to a single physical partition.
Integer	getMaxConcurrentBatchPrefetch() Gets the maximum number of per-physical-partition batches whose first page is prefetched concurrently.
Integer	getMaxItemCount() Gets the maximum number of items returned in a single page.
ReadConsistencyStrategy	getReadConsistencyStrategy() Gets the read consistency strategy for the request.
String	getSessionToken() Gets the session token for use with session consistency.
Duration	getThresholdForDiagnosticsOnTracer() Gets the latency threshold for diagnostics on tracer.
String	getThroughputControlGroupName() Gets the throughput control group name.
boolean	isQueryMetricsEnabled() Gets the option to enable populate query metrics.
CosmosReadManyByPartitionKeysRequestOptions	setAdditionalHeaders(Map<CosmosAdditionalHeaderName,String> additionalHeaders) Sets additional headers to be included with this specific request.
CosmosReadManyByPartitionKeysRequestOptions	setContinuationToken(String continuationToken) Sets the composite continuation token used to resume a previous readManyByPartitionKeys invocation.
CosmosReadManyByPartitionKeysRequestOptions	setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig) Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request.
CosmosReadManyByPartitionKeysRequestOptions	setCustomItemSerializer(CosmosItemSerializer customItemSerializer) Sets a custom item serializer to be used for this operation.
CosmosReadManyByPartitionKeysRequestOptions	setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions) Sets the dedicated gateway request options.
CosmosReadManyByPartitionKeysRequestOptions	setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds) Allows overriding the diagnostic thresholds for a specific operation.
CosmosReadManyByPartitionKeysRequestOptions	setExcludedRegions(List<String> excludeRegions) List of regions to be excluded for the request/retries.
CosmosReadManyByPartitionKeysRequestOptions	setKeywordIdentifiers(Set<String> keywordIdentifiers) Sets the custom keyword identifiers.
CosmosReadManyByPartitionKeysRequestOptions	setMaxBackendContinuationTokenSizeInKb(int limitInKb) Sets the maximum size (in kilobytes) of the backend continuation token embedded inside the composite readManyByPartitionKeys continuation token.
CosmosReadManyByPartitionKeysRequestOptions	setMaxBatchSize(int maxBatchSize) Sets the maximum number of partition key values per batch query sent to a single physical partition.
CosmosReadManyByPartitionKeysRequestOptions	setMaxConcurrentBatchPrefetch(int maxConcurrentBatchPrefetch) Sets the maximum number of per-physical-partition batches whose first page is prefetched concurrently.
CosmosReadManyByPartitionKeysRequestOptions	setMaxItemCount(int maxItemCount) Sets the maximum number of items returned in a single page.
CosmosReadManyByPartitionKeysRequestOptions	setQueryMetricsEnabled(boolean queryMetricsEnabled) Sets the option to enable/disable query metrics.
CosmosReadManyByPartitionKeysRequestOptions	setReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy) Sets the read consistency strategy required for the request.
CosmosReadManyByPartitionKeysRequestOptions	setSessionToken(String sessionToken) Sets the session token for use with session consistency.
CosmosReadManyByPartitionKeysRequestOptions	setThresholdForDiagnosticsOnTracer(Duration thresholdForDiagnosticsOnTracer) Sets the latency threshold for diagnostics on tracer.
CosmosReadManyByPartitionKeysRequestOptions	setThroughputControlGroupName(String throughputControlGroupName) Sets the throughput control group name.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Details

CosmosReadManyByPartitionKeysRequestOptions

public CosmosReadManyByPartitionKeysRequestOptions()

Instantiates a new readManyByPartitionKeys 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

getContinuationToken

public String getContinuationToken()

Gets the composite continuation token used to resume a previous readManyByPartitionKeys invocation.

Returns:

the continuation token, or null if not set.

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.

Returns:

the diagnostic thresholds for this operation.

getExcludedRegions

public List<String> getExcludedRegions()

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

Returns:

the list of excluded regions

getKeywordIdentifiers

public Set<String> getKeywordIdentifiers()

Gets the custom keyword identifiers.

Returns:

the custom keyword identifiers.

getMaxBackendContinuationTokenSizeInKb

public int getMaxBackendContinuationTokenSizeInKb()

Gets the maximum size (in kilobytes) of the backend continuation token embedded inside the composite readManyByPartitionKeys continuation token. Returns 0 if not set.

Returns:

the configured backend continuation token size limit, or 0 if not set.

getMaxBatchSize

public Integer getMaxBatchSize()

Gets the maximum number of partition key values per batch query sent to a single physical partition. Returns null if not set, in which case the SDK default is used (currently 100, configurable globally via the system property or environment variable COSMOS.READ_MANY_BY_PK_MAX_BATCH_SIZE).

Returns:

the max batch size, or null if the SDK default is in effect.

getMaxConcurrentBatchPrefetch

public Integer getMaxConcurrentBatchPrefetch()

Gets the maximum number of per-physical-partition batches whose first page is prefetched concurrently. This bounds the prefetch parallelism the SDK uses while sequentially draining batches.

Returns:

the max concurrent batch prefetch, or null if the SDK default is in effect.

getMaxItemCount

public Integer getMaxItemCount()

Gets the maximum number of items returned in a single page.

Returns:

the max item count, or null if not set (the SDK default applies).

getReadConsistencyStrategy

public ReadConsistencyStrategy getReadConsistencyStrategy()

Gets the read consistency strategy for the request.

Returns:

the read consistency strategy.

getSessionToken

public String getSessionToken()

Gets the session token for use with session consistency.

Returns:

the session token.

getThresholdForDiagnosticsOnTracer

public Duration getThresholdForDiagnosticsOnTracer()

Gets the latency threshold for diagnostics on tracer.

Returns:

the latency threshold for diagnostics on tracer.

getThroughputControlGroupName

public String getThroughputControlGroupName()

Gets the throughput control group name.

Returns:

the throughput control group name.

isQueryMetricsEnabled

public boolean isQueryMetricsEnabled()

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

Returns:

whether query metrics are enabled

setAdditionalHeaders

public CosmosReadManyByPartitionKeysRequestOptions 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 CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setContinuationToken

public CosmosReadManyByPartitionKeysRequestOptions setContinuationToken(String continuationToken)

Sets the composite continuation token used to resume a previous readManyByPartitionKeys invocation. The token must have been returned by a prior invocation of readManyByPartitionKeys on the same container, with the same partition-key set and the same custom query.

Parameters:

continuationToken - the composite continuation token from a previous invocation.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setCosmosEndToEndOperationLatencyPolicyConfig

public CosmosReadManyByPartitionKeysRequestOptions setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig cosmosEndToEndOperationLatencyPolicyConfig)

Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request.

Parameters:

cosmosEndToEndOperationLatencyPolicyConfig - the CosmosEndToEndOperationLatencyPolicyConfig

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setCustomItemSerializer

public CosmosReadManyByPartitionKeysRequestOptions setCustomItemSerializer(CosmosItemSerializer customItemSerializer)

Sets a custom item serializer to be used for this operation.

Parameters:

customItemSerializer - the custom item serializer for this operation.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setDedicatedGatewayRequestOptions

public CosmosReadManyByPartitionKeysRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)

Sets the dedicated gateway request options.

Parameters:

dedicatedGatewayRequestOptions - the dedicated gateway request options.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setDiagnosticsThresholds

public CosmosReadManyByPartitionKeysRequestOptions setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds)

Allows overriding the diagnostic thresholds for a specific operation.

Parameters:

operationSpecificThresholds - the diagnostic threshold override for this operation

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setExcludedRegions

public CosmosReadManyByPartitionKeysRequestOptions setExcludedRegions(List<String> excludeRegions)

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

Parameters:

excludeRegions - the regions to exclude

Returns:

the CosmosReadManyByPartitionKeysRequestOptions

setKeywordIdentifiers

public CosmosReadManyByPartitionKeysRequestOptions setKeywordIdentifiers(Set<String> keywordIdentifiers)

Sets the custom keyword identifiers.

Parameters:

keywordIdentifiers - the custom keyword identifiers.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setMaxBackendContinuationTokenSizeInKb

public CosmosReadManyByPartitionKeysRequestOptions setMaxBackendContinuationTokenSizeInKb(int limitInKb)

Sets the maximum size (in kilobytes) of the backend continuation token embedded inside the composite readManyByPartitionKeys continuation token.

Note: this only constrains the per-batch backend continuation that the SDK wraps inside the public composite token; the public composite token itself is always larger because it also carries the remaining batch definitions, query hash, and partition-key-set hash.

Parameters:

limitInKb - backend continuation token size limit (must be >= 1).

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setMaxBatchSize

public CosmosReadManyByPartitionKeysRequestOptions setMaxBatchSize(int maxBatchSize)

Sets the maximum number of partition key values per batch query sent to a single physical partition. The default is 100 (overridable globally via the system property COSMOS.READ_MANY_BY_PK_MAX_BATCH_SIZE). This per-request setting takes precedence over the global default.

Increasing this value reduces the number of batches (and round-trips) but produces larger IN-clause queries that consume more RUs per request. Decreasing it increases the number of batches but keeps individual requests lighter.

Parameters:

maxBatchSize - the maximum number of PKs per batch (must be >= 1).

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setMaxConcurrentBatchPrefetch

public CosmosReadManyByPartitionKeysRequestOptions setMaxConcurrentBatchPrefetch(int maxConcurrentBatchPrefetch)

Sets the maximum number of per-physical-partition batches whose first page is prefetched concurrently. The default is Math.max(1, Math.min(Runtime.getRuntime().availableProcessors(), 8)).

Increase this to trade memory for lower end-to-end latency on wide containers; decrease it (e.g. to 1) when running in environments where a single task already saturates the network/CPU and additional prefetch only adds memory pressure.

Parameters:

maxConcurrentBatchPrefetch - the max concurrent batch prefetch (must be >= 1).

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setMaxItemCount

public CosmosReadManyByPartitionKeysRequestOptions setMaxItemCount(int maxItemCount)

Sets the maximum number of items returned in a single page.

Parameters:

maxItemCount - the maximum number of items per page.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setQueryMetricsEnabled

public CosmosReadManyByPartitionKeysRequestOptions setQueryMetricsEnabled(boolean queryMetricsEnabled)

Sets the option to enable/disable query metrics.

Parameters:

queryMetricsEnabled - whether to enable or disable query metrics

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setReadConsistencyStrategy

public CosmosReadManyByPartitionKeysRequestOptions setReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy)

Sets the read consistency strategy required for the request.

Parameters:

readConsistencyStrategy - the read consistency strategy.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setSessionToken

public CosmosReadManyByPartitionKeysRequestOptions setSessionToken(String sessionToken)

Sets the session token for use with session consistency.

Parameters:

sessionToken - the session token.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setThresholdForDiagnosticsOnTracer

public CosmosReadManyByPartitionKeysRequestOptions setThresholdForDiagnosticsOnTracer(Duration thresholdForDiagnosticsOnTracer)

Sets the latency threshold for diagnostics on tracer.

Parameters:

thresholdForDiagnosticsOnTracer - the latency threshold for diagnostics on tracer.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

setThroughputControlGroupName

public CosmosReadManyByPartitionKeysRequestOptions setThroughputControlGroupName(String throughputControlGroupName)

Sets the throughput control group name.

Parameters:

throughputControlGroupName - the throughput control group name.

Returns:

the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.