{"id":3587,"date":"2021-11-02T08:00:05","date_gmt":"2021-11-02T15:00:05","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=3587"},"modified":"2023-05-05T07:13:22","modified_gmt":"2023-05-05T14:13:22","slug":"partial-document-update-ga","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/partial-document-update-ga\/","title":{"rendered":"Now Generally Available \u2013 Partial Document Update in Azure Cosmos DB"},"content":{"rendered":"

By Saranya Sriram, Abhishek Gupta<\/p>\n

\n

We’re excited to announce the general availability of <\/span><\/span>partial document update for the Azure Cosmos DB <\/span>Core (<\/span>SQL<\/span>)<\/span>\u00a0API<\/span><\/span><\/a>, which was announced at Microsoft Ignite!<\/span>\u00a0<\/span>This new feature makes it possible to<\/span> perform path-level updates to specific fields\/properties in a single document without needing to perform a full document read-replace operation.\u00a0<\/span><\/span>Partial document update is currently supported in Azure Cosmos DB .NET SDK<\/a>,\u00a0Java SDK<\/a>,\u00a0Node SDK<\/a>,\u00a0and\u00a0stored procedures<\/a>.<\/p>\n

Document updates – then and now<\/h3>\n

To put things in context, here is a refresher on how one would typically use a document replace operation:\u00a0<\/span>Read the document, u<\/span>pdate it locally (client side) including any <\/span>optimistic \u00a0<\/span><\/a>concurrency\u00a0control<\/span> (OCC) checks if necessary and, finally call the<\/span>\u00a0replace\u00a0operation along\u00a0with the updated document.<\/span>\u00a0<\/span><\/p>\n

Here is a trimmed down example of how one would use partial document update (<\/span>using\u00a0the\u00a0Java SDK<\/span>):<\/span>\u00a0<\/span><\/p>\n

\/\/step 1\u00a0\r\n\r\nUserInfo user = container.readItem(user.getId(), new PartitionKey(user.getEmail()), UserInfo.class);\u00a0\r\n\r\n\u00a0\r\n\/\/step 2\u00a0\r\n\r\nCosmosPatchOperations patchOps = CosmosPatchOperations.create().add(\"\/phone\/2\",12345).set(\"\/address\",\"123 Foobar\");\u00a0\r\n\r\n\u00a0\r\n\/\/step 3\u00a0\r\n\r\ncontainer.patchItem(user.getId(), new PartitionKey(user.getEmail()), patchOps, reqOps, UserInfo.class);<\/pre>\n
    \n
  1. Read the document (this is the same as\u00a0replace) with\u00a0<\/span>readItem<\/span><\/a>\u00a0<\/span>method.<\/span>\u00a0<\/span><\/li>\n
  2. Define the updates you want to make (in form of a\u00a0<\/span>CosmosPatchOperations<\/span><\/a>\u00a0object\u00a0\u2013 in this case we add\u00a0a\u00a0<\/span>phone<\/span><\/i>\u00a0number (an array) and set the\u00a0<\/span>address<\/span><\/i>\u00a0to\u00a0a\u00a0different one.<\/span>\u00a0<\/span><\/li>\n
  3. Invoke the\u202f<\/span>patchItem<\/span>\u202f<\/span><\/a>method.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
    Benefits of partial document update<\/span><\/b>\u00a0<\/span><\/h3>\n
    When compared with the replace operation, the overhead of serializing the entire document is eliminated since the client application <\/span>only\u00a0<\/span><\/i>needs to deal with properties to be updated (<\/span>phone<\/span><\/i>\u00a0and\u00a0<\/span>address<\/span><\/i> 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.<\/span><\/p>\n
    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.<\/span>\u00a0<\/span><\/p>\n
    Some of the other developer productivity benefits that are a by-product of the flexible\u00a0programming model enabled by partial document update:<\/span>\u00a0<\/span><\/p>\n