CosmosPatchOperations
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]
}
}
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public final class CosmosPatchOperations extends Object
Modifier and Type | Method and Description |
---|---|
<T> CosmosPatchOperations |
add(String path,
T value)
Deprecated.
|
static CosmosPatchOperations |
create()
Deprecated.
|
CosmosPatchOperations |
increment(String path,
double value)
Deprecated.
|
CosmosPatchOperations |
increment(String path,
long value)
Deprecated.
|
CosmosPatchOperations |
remove(String path)
Deprecated.
|
<T> CosmosPatchOperations |
replace(String path,
T value)
Deprecated.
|
<T> CosmosPatchOperations |
set(String path,
T value)
Deprecated.
|
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public static CosmosPatchOperations create()
CosmosPatchOperations
that will contain operations to be performed on a item atomically.CosmosPatchOperations
.@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public <T> CosmosPatchOperations add(String path, T value)
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.T
- The type of item to be added.path
- the operation path.value
- the value which will be added.CosmosPatchOperations
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public CosmosPatchOperations remove(String path)
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.path
- the operation path.CosmosPatchOperations
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public <T> CosmosPatchOperations replace(String path, T value)
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.T
- The type of item to be replaced.path
- the operation path.value
- the value which will be replaced.CosmosPatchOperations
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public <T> CosmosPatchOperations set(String path, T value)
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.T
- The type of item to be set.path
- the operation path.value
- the value which will be set.CosmosPatchOperations
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public CosmosPatchOperations increment(String path, long value)
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.path
- the operation path.value
- the value which will be incremented.CosmosPatchOperations
@Beta(value=V4_11_0, warningText="Preview API - subject to change in non-backwards compatible way") @Deprecated public CosmosPatchOperations increment(String path, double value)
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.path
- the operation path.value
- the value which will be incremented.CosmosPatchOperations
Copyright © 2021 Microsoft Corporation. All rights reserved.