By Saranya Sriram, Abhishek Gupta
We’re excited to announce the general availability of partial document update for the Azure Cosmos DB Core (SQL)ย API, which was announced at Microsoft Ignite!ย This new feature makes it possible to perform path-level updates to specific fields/properties in a single document without needing to perform a full document read-replace operation.ย Partial document update is currently supported in Azure Cosmos DB .NET SDK,ย Java SDK,ย Node SDK,ย andย stored procedures.
Document updates – then and now
To put things in context, here is a refresher on how one would typically use a document replace operation:ย Read the document, update it locally (client side) including any optimistic ย concurrencyย control (OCC) checks if necessary and, finally call theย replaceย operation alongย with the updated document.ย
Here is a trimmed down example of how one would use partial document update (usingย theย Java SDK):ย
//step 1ย
UserInfo user = container.readItem(user.getId(), new PartitionKey(user.getEmail()), UserInfo.class);ย
ย
//step 2ย
CosmosPatchOperations patchOps = CosmosPatchOperations.create().add("/phone/2",12345).set("/address","123 Foobar");ย
ย
//step 3ย
container.patchItem(user.getId(), new PartitionKey(user.getEmail()), patchOps, reqOps, UserInfo.class);
- Read the document (this is the same asย replace) withย readItemย method.ย
- Define the updates you want to make (in form of aย CosmosPatchOperationsย objectย โ in this case we addย aย phoneย number (an array) and set theย addressย toย aย different one.ย
- Invoke theโฏpatchItemโฏmethod.ย
Benefits of partial document updateย
When compared with the replace operation, the overhead of serializing the entire document is eliminated since the client application onlyย needs to deal with properties to be updated (phoneย andย address in this example). This becomes significant when your application makes frequent updates to only a few properties in your documents, such as incrementing counters, toggling true/false flags or similar types of changes.
Not having to send the entire document over the wire impacts overall application performance – reduced network bandwidth usage, lower end-to end-latency and savings of CPU cycles on the Azure Cosmos DB SDK client hosts.ย
Some of the other developer productivity benefits that are a by-product of the flexibleย programming model enabled by partial document update:ย
- Combining multiple operations:ย Partialย document update supportsย different types of operationsย (see next section). Depending on your requirements, youย canย combine multipleย suchย operationsย as part of a single invocation as opposed to incurring cost ofย round trips for separate operation type.ย
- Conditional update: If you want the partial update to depend on a pre-condition, you canย define itย usingย aย SQL-like filter predicate (for example,ย from c whereย c.taskNumย = 3).ย The partial updateย operationย willย fail if the pre-condition specified in the predicate is not satisfied.ย
- Transactions support:ย Partial document update works in the context of aย Transactional batch as well.ย This means that multiple documents within the same partition key can be patchedย (partially updated)ย as part of a transactionย (along with other operations such as create). The transactionย will be committed only if all the operations succeed. If any operation fails, the entire transaction is rolled back.ย
- Transparentย conflict resolution:ย If your Azure Cosmos DB account is configured with multiple write regions,ย conflicts andย respectiveย resolution policies are applicable at the document level (with Last Write Wins being the default conflict resolution policy). This works differently in case of partial document updates – conflicts that occur due to concurrent patch operations to the same document across multiple regions will be detected and resolved at the path-level. Thisย means that as long as youโre updatingย differentย propertiesย (paths)ย in theย sameย document, they will be merged successfully.ย
Partialย document update operationsย
Although Partial document update is a top-level operation (just like Replace), it supports sub-operations (the code snippet above used add and set). You canย refer to the documentation for details, but here is a summary:
- Add: Creates a new element (if it does not already exist).ย
- Set: Updates an element (creates one if it does not already exist).
- Replace: Updates an element only if it already exists.ย
- Remove: Deletes an existing element.ย
- Increment: Increases/decreases by specified value (use negative value to decrease).ย
Learn moreย
Find out more about Azure Cosmos DB partial document update:ย
- Read the conceptsย
- Code samplesย to get you startedย
- Add/Set/Replaceย operations โย how are theyย similar,ย yet differentย
- Frequently asked questionsย
Get started free with Azure Cosmos DB.
Hi @Abhishek,
Will Spring data cosmos support this?
Hi Abhishek,
I suppose this PatchOperation also helps in getting rid of handling OCC by developers as patching is supposed to be atomic in this case (when clients are updating different paths of same document at same time). Please correct me if I am wrong.
Hi Rishabh,
If what you’re describing (“clients are updating different paths of same document at same time”) happens in a multi-region setup, conflict resolution is handled transparently – https://docs.microsoft.com/en-us/azure/cosmos-db/partial-document-update#document-level-vs-path-level-conflict-resolution
In case of same (single) region, existing OCC rules apply https://docs.microsoft.com/en-us/azure/cosmos-db/sql/database-transactions-optimistic-concurrency#optimistic-concurrency-control
I tried via Java for partial update which did worked for me as expected.
Is there a way we can do this in Scala. I am using the Java SDK in my spark cluster and I wanted to do a patchAdd :-
I have retrieved my record and saved as dataframe in scala-spark. Now I want to add the below in the dataframe to do an patchadd like below:
CosmosPatchOperations patchOps = CosmosPatchOperations.create().add(“/phone/2”,12345).set(“/address”,”123 Foobar”);
container.patchItem(user.getId(), new PartitionKey(user.getEmail()), patchOps, reqOps, UserInfo.class);
how can we do this in SCALA-SHELL? is it possible
Where can I get details on the updates for the stored procedure server side SDK? I don’t see any updates on the existing documentation other than the one single example.
Hello Justin,
We will be adding details soon. Appreciate your patience! Do you mind providing a bit more detail on what you’re looking for in terms of stored procedures?
Hello Justin,
Documentation for is updated with more details . Hope this helps
I tried to use the new patch operations like “PatchItemAsync” on an existing C# application and existing Cosmos DB subscription with SQL SDK 3.22.1 (via Nuget).
But I get always the compile error “Error CS1061 ‘Container’ does not contain a definition for ‘PatchItemAsync’ and no accessible extension method ‘PatchItemAsync’ accepting a first argument of type ‘Container’ could be found (are you missing a using directive or an assembly reference?)”
Do I use the wrong SDK version? Or what other reason could be?
thx.
Hi Tom,
Can you please check if you’re using the version specified here https://docs.microsoft.com/en-us/azure/cosmos-db/partial-document-update-getting-started ?
Thanks!