com.azure.cosmos

Class CosmosPatchOperations

java.lang.Object

com.azure.cosmos.CosmosPatchOperations

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public final class CosmosPatchOperations
extends Object

Grammar is a super set of this RFC: https://tools.ietf.org/html/rfc6902#section-4.1 Contains a list of Patch operations to be applied on an item. It is applied in an atomic manner and we support all the operation in above RFC and more. This can be executed in 3 ways: 1. Passing this to container in container.patchItem() which requires the id of the item to be patched, partition key, the CosmosPatchOperations instance, any CosmosItemRequestOptions and the class type for which response will be parsed. 2. Add CosmosPatchOperations instance in TransactionalBatch using batch.patchItemOperation() which requires the id of the item to be patched, cosmos patch instance and TransactionalBatchItemRequestOptions(if-any) and follow remaining steps for batch for it's execution. 3. Create a bulk item using BulkOperations.getPatchItemOperation which requires the id of the item to be patched, cosmos patch instance, partition key and BulkItemRequestOptions(if-any) and follow remaining steps to execute bulk operations. Let's assume this is the JSON for which we want to run patch operation. { a : "xyz" b : { c : "efg: d : 4 e : [0, 1, 2 , 3] } }

Method Summary

Modifier and Type	Method and Description
<T> CosmosPatchOperations	add(String path, T value) This performs one of the following functions, depending upon what the target location references: 1.
static CosmosPatchOperations	create() Initializes a new instance of CosmosPatchOperations that will contain operations to be performed on a item atomically.
CosmosPatchOperations	increment(String path, double value) This increment the value at the target location.
CosmosPatchOperations	increment(String path, long value) This increment the value at the target location.
CosmosPatchOperations	remove(String path) This removes the value at the target location.
<T> CosmosPatchOperations	replace(String path, T value) This replaces the value at the target location with a new value.
<T> CosmosPatchOperations	set(String path, T value) This sets the value at the target location with a new value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public static CosmosPatchOperations create()

Initializes a new instance of CosmosPatchOperations that will contain operations to be performed on a item atomically.

Returns:

A new instance of CosmosPatchOperations.

add

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosPatchOperations add(String path,
                                                                                                                                               T value)

This performs one of the following functions, depending upon what the target location references: 1. Target location specifies an array index, a new value is inserted into the array at the specified index. 2. Target location specifies an object member that does not already exist, a new member is added to the object. 3. Target location specifies an object member that does exist, that member's value is replaced. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.add("/b/e", 15); // will add a value to the array, so /b/e array will become [0, 1, 2, 3, 15] cosmosPatch.add("/a", "new value"); // will replace the value cosmosPatch.add("/b/e/1", 10); // will change value of the /b/e array to [0, 10, 2, 3] This operation is not idempotent for scenario 1 and 2. For 3rd it is as the final value will be the value provided here.

Type Parameters:

T - The type of item to be added.

Parameters:

path - the operation path.

value - the value which will be added.

Returns:

same instance of CosmosPatchOperations

remove

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosPatchOperations remove(String path)

This removes the value at the target location. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.remove("/a"); cosmosPatch.remove("/b/e/3"); // will remove 4th element of /b/e array This operation is not idempotent. Since once applied, next time it will return bad request due to path not found.

Parameters:

path - the operation path.

Returns:

same instance of CosmosPatchOperations

replace

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosPatchOperations replace(String path,
                                                                                                                                                   T value)

This replaces the value at the target location with a new value. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.replace("/a", "new value"); // will replace "xyz" to "new value" cosmosPatch.replace("/b/e/1", 2); // will replace 2nd element of /b/e array to 2 This operation is idempotent as multiple call execution replace to the same value.

Type Parameters:

T - The type of item to be replaced.

Parameters:

path - the operation path.

value - the value which will be replaced.

Returns:

same instance of CosmosPatchOperations

set

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public <T> CosmosPatchOperations set(String path,
                                                                                                                                               T value)

This sets the value at the target location with a new value. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.set("/f", "new value"); // will add a new path "/f" and set it's value as "new value". cosmosPatch.set("/b/e", "bar"); // will set "/b/e" path to be "bar". This operation is idempotent as multiple execution will set the same value. If a new path is added, next time same value will be set.

Type Parameters:

T - The type of item to be set.

Parameters:

path - the operation path.

value - the value which will be set.

Returns:

same instance of CosmosPatchOperations

increment

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosPatchOperations increment(String path,
                                                                                                                                                 long value)

This increment the value at the target location. It's a CRDT operator and won't cause any conflict. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.increment("/b/d", 1); // will add 1 to "/b/d" resulting in 5. This is not idempotent as multiple execution will increase the value by the given increment. For multi-region we do support concurrent increment on different regions and the final value is a merged value combining all increments value. However if multiple increments are on the same region, it can lead to concurrency issue which can be retried.

Parameters:

path - the operation path.

value - the value which will be incremented.

Returns:

same instance of CosmosPatchOperations

increment

@Beta(value=V4_11_0,
      warningText="Preview API - subject to change in non-backwards compatible way")
public CosmosPatchOperations increment(String path,
                                                                                                                                                 double value)

This increment the value at the target location. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.increment("/b/d", 3.5); // will add 3.5 to "/b/d" resulting in 7.5. This is not idempotent as multiple execution will increase the value by the given increment. For multi-region we do support concurrent increment on different regions and the final value is a merged value combining all increments values. However if multiple increments are on the same region, it can lead to concurrency issue which can be retried.

Parameters:

path - the operation path.

value - the value which will be incremented.

Returns:

same instance of CosmosPatchOperations