Package com.azure.cosmos.models

Class CosmosBulkExecutionOptions

java.lang.Object
com.azure.cosmos.models.CosmosBulkExecutionOptions
public final class CosmosBulkExecutionOptions extends Object
Encapsulates options that can be specified for operations used in Bulk execution. It can be passed while processing bulk operations.

  • Constructor Details

    • CosmosBulkExecutionOptions

      public CosmosBulkExecutionOptions(CosmosBulkExecutionThresholdsState thresholdsState)
      Constructor
      Parameters:
      thresholdsState - thresholds

    • CosmosBulkExecutionOptions

      public CosmosBulkExecutionOptions()
      Constructor

  • Method Details

    • getInitialMicroBatchSize

      public int getInitialMicroBatchSize()
      Gets the initial size of micro batches that will be sent to the backend. The size of micro batches will be dynamically adjusted based on the throttling rate. The default value is 100 - so, it starts with relatively large micro batches and when the throttling rate is too high, it will reduce the batch size. When the short spikes of throttling before dynamically reducing the initial batch size results in side effects for other workloads the initial micro batch size can be reduced - for example set to 1 - at which point it would start with small micro batches and then increase the batch size over time.
      Returns:
      the initial micro batch size

    • setInitialMicroBatchSize

      public CosmosBulkExecutionOptions setInitialMicroBatchSize(int initialMicroBatchSize)
      Sets the initial size of micro batches that will be sent to the backend. The size of micro batches will be dynamically adjusted based on the throttling rate. The default value is 100 - so, it starts with relatively large micro batches and when the throttling rate is too high, it will reduce the batch size. When the short spikes of throttling before dynamically reducing the initial batch size results in side effects for other workloads the initial micro batch size can be reduced - for example set to 1 - at which point it would start with small micro batches and then increase the batch size over time.
      Parameters:
      initialMicroBatchSize - the initial micro batch size to be used. Must be a positive integer.
      Returns:
      the bulk execution options.

    • getMaxMicroBatchSize

      public int getMaxMicroBatchSize()
      The maximum batch size for bulk operations. Once queued docs exceed this value, the micro batch will be flushed to the wire.
      Returns:
      the max micro batch size.

    • setMaxMicroBatchSize

      public CosmosBulkExecutionOptions setMaxMicroBatchSize(int maxMicroBatchSize)
      The maximum batch size for bulk operations. Once queued docs exceed this value, the micro batch will be flushed to the wire.
      Parameters:
      maxMicroBatchSize - maximum batching size.
      Returns:
      the bulk processing options.

    • getCustomItemSerializer

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

    • setCustomItemSerializer

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

    • getMaxMicroBatchConcurrency

      public int getMaxMicroBatchConcurrency()
      The maximum concurrency for executing requests for a partition key range. By default, the maxMicroBatchConcurrency is 1.
      Returns:
      max micro batch concurrency

    • setMaxMicroBatchConcurrency

      public CosmosBulkExecutionOptions setMaxMicroBatchConcurrency(int maxMicroBatchConcurrency)
      Set the maximum concurrency for executing requests for a partition key range. By default, the maxMicroBatchConcurrency is 1. It only allows values ≥1 and ≤5. Attention! Please adjust this value with caution. By increasing this value, more concurrent requests will be allowed to be sent to the server, in which case may cause 429 or request timed out due to saturate local resources, which could degrade the performance.
      Parameters:
      maxMicroBatchConcurrency - the micro batch concurrency.
      Returns:
      the bulk processing options.

    • getThresholdsState

      public CosmosBulkExecutionThresholdsState getThresholdsState()
      Returns threshold state that can be passed to other CosmosBulkExecutionOptions in the future
      Returns:
      thresholds

    • setAdditionalHeaders

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

    • getThroughputControlGroupName

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

    • setThroughputControlGroupName

      public CosmosBulkExecutionOptions setThroughputControlGroupName(String throughputControlGroupName)
      Sets the throughput control group name.
      Parameters:
      throughputControlGroupName - the throughput control group name.
      Returns:
      the CosmosBulkExecutionOptions.

    • setExcludedRegions

      public CosmosBulkExecutionOptions setExcludedRegions(List<String> excludeRegions)
      List of regions to exclude 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 - list of regions
      Returns:
      the CosmosBulkExecutionOptions

    • getExcludedRegions

      public List<String> getExcludedRegions()
      Gets the list of regions to be excluded for the request/retries. These regions are excluded from the preferred region list.
      Returns:
      a list of excluded regions

    • setKeywordIdentifiers

      public CosmosBulkExecutionOptions setKeywordIdentifiers(Set<String> keywordIdentifiers)
      Sets the custom ids.
      Parameters:
      keywordIdentifiers - the custom ids.
      Returns:
      the current request options.

    • getKeywordIdentifiers

      public Set<String> getKeywordIdentifiers()
      Gets the custom ids.
      Returns:
      set of custom ids.