Package com.azure.cosmos.models

Class CosmosReadManyByPartitionKeysRequestOptions

java.lang.Object
com.azure.cosmos.models.CosmosReadManyByPartitionKeysRequestOptions
public final class CosmosReadManyByPartitionKeysRequestOptions extends Object
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 Details

    • CosmosReadManyByPartitionKeysRequestOptions

      public CosmosReadManyByPartitionKeysRequestOptions()
      Instantiates a new readManyByPartitionKeys request options.

  • Method Details

    • 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.

    • 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.

    • 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.

    • 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.
      Throws:
      IllegalArgumentException - if maxConcurrentBatchPrefetch is < 1.

    • 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.

    • 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.
      Throws:
      IllegalArgumentException - if maxBatchSize is < 1.

    • getReadConsistencyStrategy

      public ReadConsistencyStrategy getReadConsistencyStrategy()
      Gets the read consistency strategy for the request.
      Returns:
      the read consistency strategy.

    • setReadConsistencyStrategy

      public CosmosReadManyByPartitionKeysRequestOptions setReadConsistencyStrategy(ReadConsistencyStrategy readConsistencyStrategy)
      Sets the read consistency strategy required for the request.

      Honored across Direct, Gateway V1 (compute gateway), and Gateway V2 (thin client proxy) connection modes. GLOBAL_STRONG is rejected client-side with a CosmosException (HTTP 400) when the account's default consistency is not ConsistencyLevel.STRONG. Such failures must NOT be retried.

      Parameters:
      readConsistencyStrategy - the read consistency strategy.
      Returns:
      the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

    • getSessionToken

      public String getSessionToken()
      Gets the session token for use with session consistency.
      Returns:
      the session token.

    • 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.

    • 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.

    • 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.

    • 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).

    • 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.

    • 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.

    • 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

    • getExcludedRegions

      public List<String> getExcludedRegions()
      Gets the list of regions to exclude for the request/retries.
      Returns:
      the list of excluded regions

    • isQueryMetricsEnabled

      public boolean isQueryMetricsEnabled()
      Gets the option to enable populate query metrics. By default query metrics are enabled.
      Returns:
      whether query metrics are enabled

    • 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.

    • getThroughputControlGroupName

      public String getThroughputControlGroupName()
      Gets the throughput control group name.
      Returns:
      the throughput control group name.

    • 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.

    • getDedicatedGatewayRequestOptions

      public DedicatedGatewayRequestOptions getDedicatedGatewayRequestOptions()
      Gets the dedicated gateway request options.
      Returns:
      the dedicated gateway request options.

    • 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.

    • getThresholdForDiagnosticsOnTracer

      public Duration getThresholdForDiagnosticsOnTracer()
      Gets the latency threshold for diagnostics on tracer.
      Returns:
      the latency threshold for diagnostics on tracer.

    • 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.

    • 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.

    • getDiagnosticsThresholds

      public CosmosDiagnosticsThresholds getDiagnosticsThresholds()
      Gets the diagnostic thresholds used as an override for a specific operation.
      Returns:
      the diagnostic thresholds for this operation.

    • getCustomItemSerializer

      public CosmosItemSerializer getCustomItemSerializer()
      Gets the custom item serializer defined for this instance of request options.
      Returns:
      the custom item serializer.

    • 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.

    • setKeywordIdentifiers

      public CosmosReadManyByPartitionKeysRequestOptions setKeywordIdentifiers(Set<String> keywordIdentifiers)
      Sets the custom keyword identifiers.
      Parameters:
      keywordIdentifiers - the custom keyword identifiers.
      Returns:
      the CosmosReadManyByPartitionKeysRequestOptions for fluent chaining.

    • getKeywordIdentifiers

      public Set<String> getKeywordIdentifiers()
      Gets the custom keyword identifiers.
      Returns:
      the custom keyword identifiers.

    • 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 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.
      Throws:
      IllegalArgumentException - if the workload-id value is not a valid integer

    • 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