Package com.azure.cosmos.models

Class CosmosPatchOperations

java.lang.Object
com.azure.cosmos.models.CosmosPatchOperations
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 CosmosBulkOperations.getPatchItemOperation(String, PartitionKey, CosmosPatchOperations) which requires the id of the item to be patched, cosmos patch instance, partition key and CosmosBulkItemRequestOptions(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 Details

    • create

      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

      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

      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

      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

    • move

      public CosmosPatchOperations move(String fromPath, String toPath)
      This moves the value of an object from the source to a destination. This performs the following based on different cases: 1. Source location points to an object as value, moves the entire object to the target location. 2. Target location specifies an object member that does not already exist, a new member is added to the object. Its value is set to the value of the source location. For the above JSON, we can have something like this: CosmosPatchOperations cosmosPatch = CosmosPatchOperations.create(); cosmosPatch.move("/a", "/c/d"); // will move the value of "/a" to "/c/d" cosmosPatch.move("/b/e/1", "/d"); // will move the object at the 2nd element of the array and set it as the value of "/d". cosmosPatch.move("/b", "/c"); //It can also be used as a rename operation since now all values of "/b" will set as values of "/c".
      Parameters:
      fromPath - the source path for the operation.
      toPath - the destination path for the operation.
      Returns:
      same instance of CosmosPatchOperations

    • set

      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

      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

      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