Package com.azure.cosmos.models

Class CosmosItemRequestOptions

java.lang.Object
com.azure.cosmos.models.CosmosItemRequestOptions
Direct Known Subclasses:
CosmosPatchItemRequestOptions
public class CosmosItemRequestOptions extends Object
Encapsulates options that can be specified for a request issued to cosmos Item.

  • Constructor Details

    • CosmosItemRequestOptions

      public CosmosItemRequestOptions()
      Constructor

  • Method Details

    • getIfMatchETag

      public String getIfMatchETag()
      Gets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
      Returns:
      the ifMatchETag associated with the request.

    • setIfMatchETag

      public CosmosItemRequestOptions setIfMatchETag(String ifMatchETag)
      Sets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
      Parameters:
      ifMatchETag - the ifMatchETag associated with the request.
      Returns:
      the current request options

    • getIfNoneMatchETag

      public String getIfNoneMatchETag()
      Gets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
      Returns:
      the ifNoneMatchETag associated with the request.

    • setIfNoneMatchETag

      public CosmosItemRequestOptions setIfNoneMatchETag(String ifNoneMatchETag)
      Sets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
      Parameters:
      ifNoneMatchETag - the ifNoneMatchETag associated with the request.
      Returns:
      the current request options

    • getConsistencyLevel

      public ConsistencyLevel getConsistencyLevel()
      Gets the consistency level required for the request.
      Returns:
      the consistency level.

    • setConsistencyLevel

      public CosmosItemRequestOptions setConsistencyLevel(ConsistencyLevel consistencyLevel)
      Sets the consistency level required for the request. The effective consistency level can only be reduced 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 NOTE: If the consistency-level 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.
      Parameters:
      consistencyLevel - the consistency level.
      Returns:
      the CosmosItemRequestOptions.

    • getIndexingDirective

      public IndexingDirective getIndexingDirective()
      Gets the indexing directive (index, do not index etc).
      Returns:
      the indexing directive.

    • setIndexingDirective

      public CosmosItemRequestOptions setIndexingDirective(IndexingDirective indexingDirective)
      Sets the indexing directive (index, do not index etc).
      Parameters:
      indexingDirective - the indexing directive.
      Returns:
      the CosmosItemRequestOptions.

    • getPreTriggerInclude

      public List<String> getPreTriggerInclude()
      Gets the triggers to be invoked before the operation.
      Returns:
      the triggers to be invoked before the operation.

    • setPreTriggerInclude

      public CosmosItemRequestOptions setPreTriggerInclude(List<String> preTriggerInclude)
      Sets the triggers to be invoked before the operation.
      Parameters:
      preTriggerInclude - the triggers to be invoked before the operation.
      Returns:
      the CosmosItemRequestOptions.

    • getPostTriggerInclude

      public List<String> getPostTriggerInclude()
      Gets the triggers to be invoked after the operation.
      Returns:
      the triggers to be invoked after the operation.

    • setPostTriggerInclude

      public CosmosItemRequestOptions setPostTriggerInclude(List<String> postTriggerInclude)
      Sets the triggers to be invoked after the operation.
      Parameters:
      postTriggerInclude - the triggers to be invoked after the operation.
      Returns:
      the CosmosItemRequestOptions.

    • getSessionToken

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

    • setSessionToken

      public CosmosItemRequestOptions setSessionToken(String sessionToken)
      Sets the token for use with session consistency.
      Parameters:
      sessionToken - the session token.
      Returns:
      the CosmosItemRequestOptions.

    • isContentResponseOnWriteEnabled

      public Boolean isContentResponseOnWriteEnabled()
      Gets the boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem. If set to false, service doesn't return a payload in the response. It reduces networking and CPU load by not sending the payload back over the network and serializing it on the client. This feature does not impact RU usage for read or write operations. NOTE: This flag is also present on CosmosClientBuilder, however if specified on CosmosItemRequestOptions, it will override the value specified in CosmosClientBuilder for this request. By-default, this is null.
      Returns:
      a boolean indicating whether payload will be included in the response or not for this request.

    • setContentResponseOnWriteEnabled

      public CosmosItemRequestOptions setContentResponseOnWriteEnabled(Boolean contentResponseOnWriteEnabled)
      Sets the boolean to only return the headers and status code in Cosmos DB response in case of Create, Update and Delete operations on CosmosItem. If set to false, service doesn't return payload in the response. It reduces networking and CPU load by not sending the payload back over the network and serializing it on the client. This feature does not impact RU usage for read or write operations. By-default, this is null. NOTE: This flag is also present on CosmosClientBuilder, however if specified on CosmosItemRequestOptions, it will override the value specified in CosmosClientBuilder for this request.
      Parameters:
      contentResponseOnWriteEnabled - a boolean indicating whether payload will be included in the response or not for this request
      Returns:
      the CosmosItemRequestOptions.

    • getDedicatedGatewayRequestOptions

      public DedicatedGatewayRequestOptions getDedicatedGatewayRequestOptions()
      Gets the Dedicated Gateway Request Options
      Returns:
      the Dedicated Gateway Request Options

    • setNonIdempotentWriteRetryPolicy

      public CosmosItemRequestOptions setNonIdempotentWriteRetryPolicy(boolean nonIdempotentWriteRetriesEnabled, boolean useTrackingIdPropertyForCreateAndReplace)
      Enables automatic retries for write operations even when the SDK can't guarantee that they are idempotent. This is an override of the CosmosClientBuilder.setNonIdempotentWriteRetryPolicy(boolean, boolean) behavior for a specific request/operation.
      NOTE: the setting on the CosmosClientBuilder will determine the default behavior for Create, Replace, Upsert and Delete operations. It can be overridden on per-request base in the request options. For patch operations by default (unless overridden in the request options) retries are always disabled by default.
      - Create: retries can result in surfacing (more) 409-Conflict requests to the application when a retry tries to create a document that the initial attempt successfully created. When enabling useTrackingIdPropertyForCreateAndReplace this can be avoided for 409-Conflict caused by retries.
      - Replace: retries can result in surfacing (more) 412-Precondition failure requests to the application when a replace operations are using a pre-condition check (etag) and a retry tries to update a document that the initial attempt successfully updated (causing the etag to change). When enabling useTrackingIdPropertyForCreateAndReplace this can be avoided for 412-Precondition failures caused by retries.
      - Delete: retries can result in surfacing (more) 404-NotFound requests when a delete operation is retried and the initial attempt succeeded. Ideally, write retries should only be enabled when applications can gracefully handle 404 - Not Found.
      - Upsert: retries can result in surfacing a 200 - looking like the document was updated when actually the document has been created by the initial attempt - so logically within the same operation. This will only impact applications who have special casing for 201 vs. 200 for upsert operations.
      Patch: retries for patch can but will not always be idempotent - it completely depends on the patch operations being executed and the precondition filters being used. Before enabling write retries for patch this needs to be carefully reviewed and tests - which is wht retries for patch can only be enabled on request options - any CosmosClient wide configuration will be ignored.
      Bulk/Delete by PK/Transactional Batch/Stroed Procedure execution: No automatic retries are supported.
      Parameters:
      nonIdempotentWriteRetriesEnabled - a flag indicating whether the SDK should enable automatic retries for an operation when idempotency can't be guaranteed because for the previous attempt a request has been sent on the network.
      useTrackingIdPropertyForCreateAndReplace - a flag indicating whether write operations can use the trackingId system property '/_trackingId' to allow identification of conflicts and pre-condition failures due to retries. If enabled, each document being created or replaced will have an additional '/_trackingId' property for which the value will be updated by the SDK. If it is not desired to add this new json property (for example due to the RU-increase based on the payload size or because it causes documents to exceed the max payload size upper limit), the usage of this system property can be disabled by setting this parameter to false. This means there could be a higher level of 409/312 due to retries - and applications would need to handle them gracefully on their own.
      Returns:
      the CosmosItemRequestOptions

    • setDedicatedGatewayRequestOptions

      public CosmosItemRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)
      Sets the Dedicated Gateway Request Options
      Parameters:
      dedicatedGatewayRequestOptions - Dedicated Gateway Request Options
      Returns:
      the CosmosItemRequestOptions

    • setCosmosEndToEndOperationLatencyPolicyConfig

      public CosmosItemRequestOptions setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig endToEndOperationLatencyPolicyConfig)
      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:
      endToEndOperationLatencyPolicyConfig - the CosmosEndToEndOperationLatencyPolicyConfig
      Returns:
      CosmosItemRequestOptions

    • setExcludedRegions

      public CosmosItemRequestOptions 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
      Parameters:
      excludeRegions - list of regions
      Returns:
      the CosmosItemRequestOptions

    • 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

    • getThroughputControlGroupName

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

    • setThroughputControlGroupName

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

    • getThresholdForDiagnosticsOnTracer

      public Duration getThresholdForDiagnosticsOnTracer()
      Gets the thresholdForDiagnosticsOnTracer, if latency on CRUD operation is greater than this diagnostics will be sent to open telemetry exporter as events in tracer span of end to end CRUD api. Default is 100 ms.
      Returns:
      thresholdForDiagnosticsOnTracerInMS the latency threshold for diagnostics on tracer.

    • setThresholdForDiagnosticsOnTracer

      public CosmosItemRequestOptions setThresholdForDiagnosticsOnTracer(Duration thresholdForDiagnosticsOnTracer)
      Sets the thresholdForDiagnosticsOnTracer, if latency on CRUD operation is greater than this diagnostics will be sent to open telemetry exporter as events in tracer span of end to end CRUD api. Default is 100 ms.
      Parameters:
      thresholdForDiagnosticsOnTracer - the latency threshold for diagnostics on tracer.
      Returns:
      the CosmosItemRequestOptions

    • setDiagnosticsThresholds

      public CosmosItemRequestOptions setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds)
      Allows overriding the diagnostic thresholds for a specific operation.
      Parameters:
      operationSpecificThresholds - the diagnostic threshold override for this operation
      Returns:
      the CosmosItemRequestOptions.

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