{"id":21036949,"url":"https://github.com/azurecosmosdb/patchprivatepreviewfeedbackgroup","last_synced_at":"2025-05-15T14:32:08.997Z","repository":{"id":46666574,"uuid":"359695034","full_name":"AzureCosmosDB/PatchPrivatePreviewFeedbackGroup","owner":"AzureCosmosDB","description":"This group will share the private preview documentation, issues for the partial update feature. ","archived":true,"fork":false,"pushed_at":"2021-10-01T07:06:26.000Z","size":3899,"stargazers_count":19,"open_issues_count":11,"forks_count":3,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-13T20:41:58.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AzureCosmosDB.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-20T05:30:43.000Z","updated_at":"2024-06-30T13:12:33.000Z","dependencies_parsed_at":"2022-09-23T18:50:27.268Z","dependency_job_id":null,"html_url":"https://github.com/AzureCosmosDB/PatchPrivatePreviewFeedbackGroup","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FPatchPrivatePreviewFeedbackGroup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FPatchPrivatePreviewFeedbackGroup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FPatchPrivatePreviewFeedbackGroup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AzureCosmosDB%2FPatchPrivatePreviewFeedbackGroup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AzureCosmosDB","download_url":"https://codeload.github.com/AzureCosmosDB/PatchPrivatePreviewFeedbackGroup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254358890,"owners_count":22058008,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T13:23:21.443Z","updated_at":"2025-05-15T14:32:07.166Z","avatar_url":"https://github.com/AzureCosmosDB.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Partial Document Update Preview -  Docs and Feedback\n\nThis documentation is provided as a resource for participants in the private preview of Azure Cosmos DB partial document update.\n\nNote: the partial document update preview is applicable to Core (SQL) API only. Users looking for partial updates in MongoDB API are advised to use the partial update operators (e.g. `$set`, `$inc`, etc) in `db.collection.update()` and `db.collection.findAndModify()`.\n\nPlease do provide us your feedback, questions or comments via the \"issues\" section on this repo (second tab on the top left)\n\n## Feature Overview\nAzure Cosmos DB partial document update is a top-level REST API to modify an item efficiently by sending only the modified properties/fields in a document from the client side as opposed to requiring the client to perform a full document replace. \n\n## Main Benefits: \n* Reduced network call payload, avoiding whole document to be sent on the wire \n* Avoiding extra “READ “operation for OCC check by the client and hence saving on the extra read RU charges\n* Significant savings on end-to-end latency for a modifying the document\n* Avoid extra CPU cycles on client side to read doc, perform occ checks, locally patch document \u0026 then send it over the wire as replace API call\n* Multi-region write (formerly \"multi-master\") conflict resolution to be transparent and automatic with path updates on discrete paths with the same document\n\n## Supported Operations, Modes, APIs \u0026 SDKs :\n#### Operations\n- Add\n- Remove\n- Replace\n- Set\n- Increment as plus or minus “x”, i.e +/- X\n\n#### Modes\n- Conditional patch based on a SQL-like filter predicate\n- Single item patch operation command\n- Multiple items patch operation in using bulk APIs\n- Transactional batch patch operation\n\n#### SDKs\n- .NET\n- Java\n- NodeJS\n\n## How to get started: \nStep 1: Whitelist your account by completing the nomination form : https://aka.ms/cosmos-partial-doc-update or emailing us cosmosdbpatchpreview@microsoft.com for specific clarifications.\n\nStep2: Download the Nuget Package /  Maven package\n- .NET Nuget Package : NuGet Gallery | Microsoft.Azure.Cosmos 3.18.0-preview or attached nuget file in this repo\n- Java Maven Package: Maven Repository: com.azure » azure-cosmos » 4.15.0-beta.1(https://mvnrepository.com/artifact/com.azure/azure-cosmos/4.15.0-beta.1)\n\nStep3: Send us your feedback, comments, questions using the Issues tab on this repo. \n\n## Note : \nDuring **preview** the JSON Patch feature can take 5-8 minutes to be enabled after Collection is created. \nThis will not happen after GA as it would be enabled by default.\nSo, for preview, ensure that you are not using newly created Collections. \nIf you do, you may experience error 500 \"An unknown error occurred while processing this request. \n\n## Sample Code\n### .NET : \nThe full sample is found at [.NET v3 samples](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/3fa885fdd84e2f8852d2a1d5c75c56b642b5bba3/Microsoft.Azure.Cosmos.Samples/Usage/ItemManagement/Program.cs)\n\n#### Patching an item with a single patch operation: \n~~~~\n//using PatchOperation command to Replace a property. The Patch is issued based on ID lookup for an id = 5, partition key value of pkey and setting TotalDues value to 0\nConsole.WriteLine(\"\\n1.6 - Patching a item using its Id\");\nItemResponse\u003citem\u003e response = await container.PatchItemAsync\u003citem\u003e(\n                id: 5,\n                partitionKey: new PartitionKey(“pkey”),\n                patchOperations: new[] { PatchOperation.Replace(\"/TotalDue\", 0) });\n~~~~\n#### Patching a document with multiple patch operations\n~~~~\n//using PatchOperation command to do multiple patches on a document. The Patch is issued based on ID lookup for an id = 5, partition key value of pkey.\nConsole.WriteLine(\"\\n1.6 - Patching a item using its Id\");\n\nList\u003cPatchOperation\u003e patchOperations = new List\u003cPatchOperation\u003e();\npatchOperations.Add(PatchOperation.Add(\"/nonExistentParent/Child\", \"bar\"));\npatchOperations.Add(PatchOperation.Remove(\"/cost\"));\npatchOperations.Add(PatchOperation.Increment(\"/taskNum\", 6));\npatchOperations.Add(patchOperation.Set(\"/existingPath/newproperty\",value));\n\ncontainer.PatchItemAsync\u003citem\u003e(\n                id: 5,\n                partitionKey: new PartitionKey(“pkey”),\n                patchOperations: patchOperations );\n~~~~\n\n#### Conditional patch syntax based on filter predicate\n~~~~\n//using Conditional Patch Operation command to replace a property. The patch is issued based on a filter predicate condition; issued to id =5, partition key “pkey” and replaing the Shipped Date to current Datetime \nPatchItemRequestOptions patchItemRequestOptions = new PatchItemRequestOptions\n{\n\tFilterPredicate = \"from c where (c.TotalDue = 0 OR NOT IS_DEFINED(c.TotalDue))\"\n};\nresponse = await container.PatchItemAsync\u003cSalesOrder\u003e(\n              id: 5,\n              partitionKey: new PartitionKey(“pkey”),\n\t      patchOperations: new[] { PatchOperation.Replace(\"/ShippedDate\",  DateTime.UtcNow) },\n                patchItemRequestOptions);\n~~~~\n\n#### Sample transactional patch for batch patch operation\n~~~~\nList\u003cPatchOperation\u003e patchOperationsUpdateTaskNum12 = new List\u003cPatchOperation\u003e()\n            {\n                PatchOperation.Add(\"/children/1/pk\", \"patched\"),\n                PatchOperation.Remove(\"/description\"),\n                PatchOperation.Add(\"/taskNum\", 8)\n\t\tPatchOperation.Replace(\"/taskNum\", 12)\n            };\n\nTransactionalBatchPatchItemRequestOptions requestOptionsFalse = new TransactionalBatchPatchItemRequestOptions()\n            {\n                FilterPredicate = \"from c where c.taskNum = 3\"\n            };\n\nTransactionalBatchInternal transactionalBatchInternalFalse = (TransactionalBatchInternal)containerInternal.CreateTransactionalBatch(new Cosmos.PartitionKey(testItem.pk));\ntransactionalBatchInternalFalse.PatchItem(id: testItem1.id, patchOperationsUpdateTaskNum12, requestOptionsFalse);\ntransactionalBatchInternalFalse.PatchItem(id: testItem2.id, patchOperationsUpdateTaskNum12, requestOptionsFalse);\ntransactionalBatchInternalFalse.ExecuteAsync());\n~~~~\n\n### Java: \nThe Maven package is found at [Maven Repository: com.azure » azure-cosmos » 4.15.0-beta.1 (mvnrepository.com)](https://mvnrepository.com/artifact/com.azure/azure-cosmos/4.15.0-beta.1)\n\n#### Patching a document with multiple patch operations\n~~~~\n//using PatchOperation command to do multiple patches on a document. The Patch is issued based on ID lookup for an testitem.id, partition key value of testitem.status.\nCosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();\ncosmosPatchOperations.add(\"/children/1/CamelCase\", \"patched\");\ncosmosPatchOperations.remove(\"/description\");\ncosmosPatchOperations.replace(\"/taskNum\", newTaskNum);\ncosmosPatchOperations.set(\"/valid\", false);\nCosmosPatchItemRequestOptions options = new CosmosPatchItemRequestOptions();\nCosmosItemResponse\u003cToDoActivity\u003e response = this.container.patchItem(\n\t            testItem.id,\n\t            new PartitionKey(testItem.status),\n\t            cosmosPatchOperations,\n\t            options,\n\t            ToDoActivity.class);\n~~~~\n\n#### Sample of a conditional patch syntax based on filter predicate\n~~~~\n//using Conditional Patch options. The patch is issued based on a filter predicate condition; issued to id = testitem.id, partition key “testitem.status” \nCosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();\ncosmosPatchOperations.add(\"/children/1/CamelCase\", \"patched\");\ncosmosPatchOperations.remove(\"/description\");\ncosmosPatchOperations.replace(\"/taskNum\", newTaskNum);\ncosmosPatchOperations.set(\"/valid\", false);\n\nCosmosPatchItemRequestOptions options = new CosmosPatchItemRequestOptions();\noptions.setFilterPredicate(\"from root where root.taskNum = \" + conditionvalue);\nCosmosItemResponse\u003cToDoActivity\u003e responseFail = this.container.patchItem(\n                testItem.id,\n                new PartitionKey(testItem.status),\n                cosmosPatchOperations,\n                options,\n                ToDoActivity.class);\n~~~~\n\n#### Sample transactional patch for batch operations\n~~~~\nCosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();\ncosmosPatchOperations.set(\"/cost\", testDoc.getCost() + 12);\n\n//for conditional filter predicate - optional\nTransactionalBatchPatchItemRequestOptions transactionalBatchPatchItemRequestOptionsTrue = new TransactionalBatchPatchItemRequestOptions();\ntransactionalBatchPatchItemRequestOptionsTrue.setFilterPredicate(\"from root where root.cost = \" + costValue);\n\nTransactionalBatch batch = TransactionalBatch.createTransactionalBatch(this.getPartitionKey(this.partitionKey1));\nbatch.createItemOperation(testDoc);\nbatch.patchItemOperation(testDoc.getId(), cosmosPatchOperations);\nTransactionalBatchResponse batchResponse = container.executeTransactionalBatch(batch).block();\n~~~~\n\n### NodeJS:\n\nThe npm package can be found at [NPM package: com.azure » @azure/cosmos » 3.14.1 (npmjs.com)](https://www.npmjs.com/package/@azure/cosmos/v/3.14.1)\n\n\n#### Patching an item with a single patch operation\n\n```\nconst replaceOperation: PatchOperation[] =\n[{\nop: \"replace\",\npath: \"/lastName\",\nvalue: \"Martin\"\n}];\nconst { resource: testItem1 } = await container.item(testItem.lastName).patch(replaceOperation);\n```\n\n#### Patching a document with multiple patch operations\n\n```\nconst multipleOperations: PatchOperation[] = [\n{\nop: \"add\",\npath: \"/aka\",\nvalue: \"MeFamily\"\n},\n{\nop: \"replace\",\npath: \"/lastName\",\nvalue: \"Jose\"\n},\n{\nop: \"remove\",\npath: \"/parents\"\n},\n{\nop: \"set\",\npath: \"/address/zip\",\nvalue: 90211\n},\n{\nop: \"incr\",\npath: \"/address/zip\",\nvalue: 5\n}\n];\nconst { resource: testItem2 } = await container.item(testItem.id).patch(multipleOperations);\n```\n\n#### Conditional patch syntax based on filter predicate\n\n```\nconst operations : PatchOperation[] = [\n{\nop: \"add\",\npath: \"/newImproved\",\nvalue: \"it works\"\n}\n];\nconst condition = \"from c where NOT IS_DEFINED(c.newImproved)\";\nconst { resource: testItem3 } = await container.item(testItem.id).patch({ condition, operations });\n```\n\n#### Sample transactional patch for bulk patch operation\n\n```\nconst operations = [    \n    {\n      operationType: BulkOperationType.Patch,\n      partitionKey: {},\n      id: patchItemId,\n      resourceBody: {\n        operations: [{ op: PatchOperationType.set, path: \"/class\", value: \"2021\" }]\n      }\n    }\n  ];\nconst response = await container.items.bulk(operations);\n```\n\n## Frequently Asked Questions (FAQs)\n\n#### Is this an implementation of JSON Patch RFC 6902?\nAzure Cosmos DB partial document update is inspired by JSON patch and follows it closely. Currently we do not implement all features of JSON patch such as (Copy, Move) and we do implement few other features (Conditional Patch) which is not in the specification\n\n#### Is partial document update compatible with serverless , provisioned throughput and autoscale modes of billing?\nPartial document update will be available across serverless and provisioned billing models. \n\n#### How is RU pricing calculated ?\nPartial document update is normalized into request unit billing in the same style as other database operations. Users should not expect a significant reduction in RU.\n\n#### What is the difference between operator Set and Replace?\nFor a detailed answer, refer to [this issue](https://github.com/AzureCosmosDB/PatchPrivatePreviewFeedbackGroup/issues/2)\n\n#### Is there a limit to the number of partial document updates operations that can be done within a single patch specification?\nThere is a limit of 10 patch operations that can be added in a single patch specification. If we need this number to be increased, please send us an [email](cosmosdbpatchpreview@microsoft.com)\n\n#### Is Patch supported for system properties?\nWe do not support Patch API on system properties. However, if you want it for some usecase, you can send an [email](cosmosdbpatchpreview@microsoft.com) and we can enable this for your account.\n\n#### Is partial document update supported on local Azure CosmosDB emulator?\nYes, please follow the below steps to enable it.\n1) Download the latest Azure CosmosDB emulator from https://aka.ms/cosmosdb-emulator\n2) Open PowerShell in admin mode\n3) cd 'C:\\Program Files\\Azure Cosmos DB Emulator'\n4) C:\\Program Files\\Azure Cosmos DB Emulator\u003e **.\\CosmosDB.Emulator.exe /EnablePreview**\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fpatchprivatepreviewfeedbackgroup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazurecosmosdb%2Fpatchprivatepreviewfeedbackgroup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazurecosmosdb%2Fpatchprivatepreviewfeedbackgroup/lists"}