CosmosItemRequestOptions Class

Package:

com.azure.cosmos.models

Maven Artifact:

com.azure:azure-cosmos:4.63.4

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

public class CosmosItemRequestOptions

Encapsulates options that can be specified for a request issued to cosmos Item.

Constructor Summary

Constructor	Description
CosmosItemRequestOptions()	Constructor

Method Summary

Modifier and Type	Method and Description
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 be excluded for the request/retries.
String	getIfMatchETag() Gets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
String	getIfNoneMatchETag() Gets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
IndexingDirective	getIndexingDirective() Gets the indexing directive (index, do not index etc).
Set<String>	getKeywordIdentifiers() Gets the custom ids.
List<String>	getPostTriggerInclude() Gets the triggers to be invoked after the operation.
List<String>	getPreTriggerInclude() Gets the triggers to be invoked before the operation.
String	getSessionToken() Gets the token for use with session consistency.
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.
String	getThroughputControlGroupName() Gets the throughput control group name.
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.
CosmosItemRequestOptions	setConsistencyLevel(ConsistencyLevel consistencyLevel) Sets the consistency level required for the request.
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.
CosmosItemRequestOptions	setCosmosEndToEndOperationLatencyPolicyConfig(CosmosEndToEndOperationLatencyPolicyConfig endToEndOperationLatencyPolicyConfig) Sets the CosmosEndToEndOperationLatencyPolicyConfig to be used for the request.
CosmosItemRequestOptions	setCustomItemSerializer(CosmosItemSerializer customItemSerializer) Allows specifying a custom item serializer to be used for this operation.
CosmosItemRequestOptions	setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions) Sets the Dedicated Gateway Request Options
CosmosItemRequestOptions	setDiagnosticsThresholds(CosmosDiagnosticsThresholds operationSpecificThresholds) Allows overriding the diagnostic thresholds for a specific operation.
CosmosItemRequestOptions	setExcludedRegions(List<String> excludeRegions) List of regions to exclude for the request/retries.
CosmosItemRequestOptions	setIfMatchETag(String ifMatchETag) Sets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
CosmosItemRequestOptions	setIfNoneMatchETag(String ifNoneMatchETag) Sets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
CosmosItemRequestOptions	setIndexingDirective(IndexingDirective indexingDirective) Sets the indexing directive (index, do not index etc).
CosmosItemRequestOptions	setKeywordIdentifiers(Set<String> keywordIdentifiers) Sets the custom ids.
CosmosItemRequestOptions	setNonIdempotentWriteRetryPolicy(boolean nonIdempotentWriteRetriesEnabled, boolean useTrackingIdPropertyForCreateAndReplace) Enables automatic retries for write operations even when the SDK can't guarantee that they are idempotent.
CosmosItemRequestOptions	setPostTriggerInclude(List<String> postTriggerInclude) Sets the triggers to be invoked after the operation.
CosmosItemRequestOptions	setPreTriggerInclude(List<String> preTriggerInclude) Sets the triggers to be invoked before the operation.
CosmosItemRequestOptions	setSessionToken(String sessionToken) Sets the token for use with session consistency.
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.
void	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

CosmosItemRequestOptions

public CosmosItemRequestOptions()

Constructor

Method Details

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

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.

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.

getIndexingDirective

public IndexingDirective getIndexingDirective()

Gets the indexing directive (index, do not index etc).

Returns:

the indexing directive.

getKeywordIdentifiers

public Set getKeywordIdentifiers()

Gets the custom ids.

Returns:

the custom ids.

getPostTriggerInclude

public List getPostTriggerInclude()

Gets the triggers to be invoked after the operation.

Returns:

the triggers to be invoked after the operation.

getPreTriggerInclude

public List getPreTriggerInclude()

Gets the triggers to be invoked before the operation.

Returns:

the triggers to be invoked before the operation.

getSessionToken

public String getSessionToken()

Gets the token for use with session consistency.

Returns:

the session token.

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.

getThroughputControlGroupName

public String getThroughputControlGroupName()

Gets the throughput control group name.

Returns:

the throughput control group name.

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.

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.

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.

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

setCustomItemSerializer

public CosmosItemRequestOptions 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 CosmosItemRequestOptions setDedicatedGatewayRequestOptions(DedicatedGatewayRequestOptions dedicatedGatewayRequestOptions)

Sets the Dedicated Gateway Request Options

Parameters:

dedicatedGatewayRequestOptions - Dedicated Gateway Request Options

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.

setExcludedRegions

public CosmosItemRequestOptions setExcludedRegions(List 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

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

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

setIndexingDirective

public CosmosItemRequestOptions setIndexingDirective(IndexingDirective indexingDirective)

Sets the indexing directive (index, do not index etc).

Parameters:

indexingDirective - the indexing directive.

Returns:

the CosmosItemRequestOptions.

setKeywordIdentifiers

public CosmosItemRequestOptions setKeywordIdentifiers(Set keywordIdentifiers)

Sets the custom ids.

Parameters:

keywordIdentifiers - the custom ids.

Returns:

the current 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 nonIdempotentWriteRetryOptions(NonIdempotentWriteRetryOptions options) 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

setPostTriggerInclude

public CosmosItemRequestOptions setPostTriggerInclude(List postTriggerInclude)

Sets the triggers to be invoked after the operation.

Parameters:

postTriggerInclude - the triggers to be invoked after the operation.

Returns:

the CosmosItemRequestOptions.

setPreTriggerInclude

public CosmosItemRequestOptions setPreTriggerInclude(List preTriggerInclude)

Sets the triggers to be invoked before the operation.

Parameters:

preTriggerInclude - the triggers to be invoked before the operation.

Returns:

the CosmosItemRequestOptions.

setSessionToken

public CosmosItemRequestOptions setSessionToken(String sessionToken)

Sets the token for use with session consistency.

Parameters:

sessionToken - the session token.

Returns:

the CosmosItemRequestOptions.

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

setThroughputControlGroupName

public void setThroughputControlGroupName(String throughputControlGroupName)

Sets the throughput control group name.

Parameters:

throughputControlGroupName - the throughput control group name.