Merge pull request #229578 from TimShererWithAquent/us2036619c

Freshness Pass User Story: 2036619 Get started with Azure Cosmos DB Partial Document Update

Author: AnnaMHuff

articles/cosmos-db/nosql/TOC.yml

@@ -476,7 +476,7 @@
           items:
             - name: Partial document update overview
               href: ../partial-document-update.md
-            - name: Getting started with Partial document update
+            - name: Get started with Partial Document Update
               href: ../partial-document-update-getting-started.md
             - name: Partial document update FAQ
               href: ../partial-document-update-faq.yml

articles/cosmos-db/partial-document-update-getting-started.md

@@ -1,33 +1,35 @@
 ---
-title: Getting started with Azure Cosmos DB Partial Document Update
-description: This article provides example for how to use Partial Document Update with .NET, Java, Node SDKs
+title: Get started with Azure Cosmos DB Partial Document Update
+description: Learn how to use Partial Document Update with .NET, Java, and Node SDKs for Azure Cosmos DB with these examples.
 author: seesharprun
 ms.service: cosmos-db
 ms.subservice: nosql
 ms.topic: how-to
-ms.date: 12/09/2021
+ms.date: 03/06/2023
 ms.author: sidandrews
 ms.custom: ignite-fall-2021, ignite-2022
 ---
 
-# Azure Cosmos DB Partial Document Update: Getting Started
+# Get started with Azure Cosmos DB Partial Document Update
 [!INCLUDE[NoSQL](includes/appliesto-nosql.md)]
 
-This article provides examples illustrating for how to use Partial Document Update with .NET, Java, and Node SDKs. This article also details common errors that you may encounter. Code samples for the following scenarios have been provided:
+This article provides examples that illustrate how to use Partial Document Update with .NET, Java, and Node SDKs. It also describes common errors that you might encounter.
 
-- Executing a single patch operation
-- Combining multiple patch operations
-- Conditional patch syntax based on filter predicate
-- Executing patch operation as part of a Transaction
+This article links to code samples for the following scenarios:
+
+- Run a single patch operation
+- Combine multiple patch operations
+- Use conditional patch syntax based on filter predicate
+- Run patch operation as part of a transaction
 
 ## [.NET](#tab/dotnet)
 
-Support for Partial document update (Patch API) in the [Azure Cosmos DB .NET v3 SDK](nosql/sdk-dotnet-v3.md) is available from version *3.23.0* onwards. You can download it from the [NuGet Gallery](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.23.0)
+Support for Partial Document Update (Patch API) in the [Azure Cosmos DB .NET v3 SDK](nosql/sdk-dotnet-v3.md) is available starting with version *3.23.0*. You can download it from the [NuGet Gallery](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.23.0).
 
 > [!NOTE]
-> A complete partial document update sample can be found in the [.NET v3 samples repository](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos.Samples/Usage/ItemManagement/Program.cs) on GitHub.
+> Find a complete Partial Document Update sample in the [.NET v3 samples repository](https://github.com/Azure/azure-cosmos-dotnet-v3/blob/master/Microsoft.Azure.Cosmos.Samples/Usage/ItemManagement/Program.cs) on GitHub.
 
-- Executing a single patch operation
+- Run a single patch operation:
 
     ```csharp
     ItemResponse<Product> response = await container.PatchItemAsync<Product>(
@@ -41,7 +43,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB .NET v3
     Product updated = response.Resource;
     ```
 
-- Combining multiple patch operations
+- Combine multiple patch operations:
 
     ```csharp
     List<PatchOperation> operations = new ()
@@ -58,7 +60,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB .NET v3
     );
     ```
 
-- Conditional patch syntax based on filter predicate
+- Use conditional patch syntax based on filter predicate:
 
     ```csharp
     PatchItemRequestOptions options = new()
@@ -79,7 +81,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB .NET v3
     );
     ```
 
-- Executing patch operation as a part of a Transaction
+- Run patch operation as a part of a transaction:
 
     ```csharp
     TransactionalBatchPatchItemRequestOptions options = new()
@@ -113,7 +115,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB .NET v3
 
 ## [Java](#tab/java)
 
-Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4 SDK](nosql/sdk-java-v4.md) is available from version *4.21.0* onwards. You can either add it to the list of dependencies in your `pom.xml` or download it directly from [Maven](https://mvnrepository.com/artifact/com.azure/azure-cosmos).
+Support for Partial Document Update (Patch API) in the [Azure Cosmos DB Java v4 SDK](nosql/sdk-java-v4.md) is available starting with version *4.21.0*. You can either add it to the list of dependencies in your `pom.xml` or download it directly from [Maven](https://mvnrepository.com/artifact/com.azure/azure-cosmos).
 
 ```xml
 <dependency>
@@ -124,9 +126,9 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4
 ```
 
 > [!NOTE]
-> The full sample can be found in the [Java SDK v4 samples repository](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/tree/main/src/main/java/com/azure/cosmos/examples/patch/sync) on GitHub
+> Find the full sample in the [Java SDK v4 samples repository](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/tree/main/src/main/java/com/azure/cosmos/examples/patch/sync) on GitHub.
 
-- Executing a single patch operation
+- Run a single patch operation:
 
     ```java
     CosmosItemResponse<Product> response = container.patchItem(
@@ -141,7 +143,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4
     Product updated = response.getItem();
     ```
 
-- Combining multiple patch operations
+- Combine multiple patch operations:
 
     ```java
     CosmosPatchOperations operations = CosmosPatchOperations
@@ -158,7 +160,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4
     );
     ```
 
-- Conditional patch syntax based on filter predicate
+- Use conditional patch syntax based on filter predicate:
 
     ```java
     CosmosPatchItemRequestOptions options = new CosmosPatchItemRequestOptions();
@@ -177,7 +179,7 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4
     );
     ```
 
-- Executing patch operation as a part of a Transaction
+- Run patch operation as a part of a transaction:
 
     ```java
     CosmosBatchPatchItemRequestOptions options = new CosmosBatchPatchItemRequestOptions();
@@ -208,14 +210,12 @@ Support for Partial document update (Patch API) in the [Azure Cosmos DB Java v4
 
 ## [Node.js](#tab/nodejs)
 
-Support for Partial document update (Patch API) in the [Azure Cosmos DB JavaScript SDK](nosql/sdk-nodejs.md) is available from version *3.15.0* onwards. You can download it from the [npm Registry](https://www.npmjs.com/package/@azure/cosmos)
+Support for Partial Document Update (Patch API) in the [Azure Cosmos DB JavaScript SDK](nosql/sdk-nodejs.md) is available starting with version *3.15.0*. You can download it from the [npm Registry](https://www.npmjs.com/package/@azure/cosmos).
 
 > [!NOTE]
-> A complete partial document update sample can be found in the [.js v3 samples repository](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/cosmosdb/cosmos/samples/v3/typescript/src/ItemManagement.ts#L167) on GitHub. In the sample, as the container is created without a partition key specified, the JavaScript SDK
-resolves the partition key values from the items through the container's partition
-key definition.
+> Find a complete Partial Document Update sample in the [.js v3 samples repository](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/cosmosdb/cosmos/samples/v3/typescript/src/ItemManagement.ts#L167) on GitHub. In the sample, as the container is created without a partition key specified, the JavaScript SDK resolves the partition key values from the items through the container's partition key definition.
 
-- Executing a single patch operation
+- Run a single patch operation:
 
     ```javascript
     const operations =
@@ -231,7 +231,7 @@ key definition.
         .patch(operations);
     ```
 
-- Combining multiple patch operations
+- Combine multiple patch operations:
 
     ```javascript
     const operations =
@@ -248,7 +248,7 @@ key definition.
         .patch(operations);
     ```
 
-- Conditional patch syntax based on filter predicate
+- Use conditional patch syntax based on filter predicate:
 
     ```javascript
     const filter = 'FROM products p WHERE p.used = false'
@@ -271,9 +271,9 @@ key definition.
 
 ---
 
-## Support for Server-Side programming
+## Support for server-side programming
 
-Partial Document Update operations can also be [executed on the server-side](stored-procedures-triggers-udfs.md) using Stored procedures, triggers, and user-defined functions.
+Partial Document Update operations can also be [executed on the server-side](stored-procedures-triggers-udfs.md) using stored procedures, triggers, and user-defined functions.
 
 ```javascript
 this.patchDocument = function (documentLink, patchSpec, options, callback) {
@@ -321,57 +321,59 @@ this.patchDocument = function (documentLink, patchSpec, options, callback) {
     );
 }; 
 ```
+
 > [!NOTE]
-> Definition of validateOptionsAndCallback can be found in the [.js DocDbWrapperScript](https://github.com/Azure/azure-cosmosdb-js-server/blob/1dbe69893d09a5da29328c14ec087ef168038009/utils/DocDbWrapperScript.js#L289) on GitHub.
+> Find the definition of `validateOptionsAndCallback` in the [.js DocDbWrapperScript](https://github.com/Azure/azure-cosmosdb-js-server/blob/1dbe69893d09a5da29328c14ec087ef168038009/utils/DocDbWrapperScript.js#L289) on GitHub.
 
-- Sample parameter for patch operation
+Sample parameter for patch operation:
 
-    ```javascript
-    function () {
-       var doc = {
-          "id": "exampleDoc",
-          "field1": {
-             "field2": 10,
-             "field3": 20
-          }
-       };
-       var isAccepted = __.createDocument(__.getSelfLink(), doc, (err, doc) => {
-             if (err) throw err;
-             var patchSpec = [
-                {"op": "add", "path": "/field1/field2", "value": 20}, 
-                {"op": "remove", "path": "/field1/field3"}
-             ];
-             isAccepted = __.patchDocument(doc._self, patchSpec, (err, doc) => {
-                   if (err) throw err;
-                   else {
-                      getContext().getResponse().setBody(docPatched);
-                   }
-                }
-             }
-             if(!isAccepted) throw new Error("patch was't accepted")
-          }
-       }
-       if(!isAccepted) throw new Error("create wasn't accepted")
-    }
-    ```
+```javascript
+function () {
+    var doc = {
+      "id": "exampleDoc",
+      "field1": {
+         "field2": 10,
+         "field3": 20
+      }
+   };
+   var isAccepted = __.createDocument(__.getSelfLink(), doc, (err, doc) => {
+         if (err) throw err;
+         var patchSpec = [
+            {"op": "add", "path": "/field1/field2", "value": 20}, 
+            {"op": "remove", "path": "/field1/field3"}
+         ];
+         isAccepted = __.patchDocument(doc._self, patchSpec, (err, doc) => {
+               if (err) throw err;
+               else {
+                  getContext().getResponse().setBody(docPatched);
+               }
+            }
+         }
+         if(!isAccepted) throw new Error("patch was't accepted")
+      }
+   }
+   if(!isAccepted) throw new Error("create wasn't accepted")
+}
+```
 
 ## Troubleshooting
 
-Here's a list of common errors that you might encounter while using this feature:
+Here's some common errors that you might encounter while using this feature:
 
 | **Error Message** | **Description** |
 | ------------ | -------- |
-| Invalid patch request: check syntax of patch specification| The Patch operation syntax is invalid. For more information, see [the partial document update specification](partial-document-update.md#rest-api-reference-for-partial-document-update)
-| Invalid patch request: Can't patch system property `SYSTEM_PROPERTY`. | System-generated properties like `_id`, `_ts`, `_etag`, `_rid` aren't modifiable using a Patch operation. For more information, see: [Partial Document Update FAQs](partial-document-update-faq.yml#is-partial-document-update-supported-for-system-generated-properties-) 
-| The number of patch operations can't exceed 10 | There's a limit of 10 patch operations that can be added in a single patch specification. For more information, see: [Partial Document Update FAQs](partial-document-update-faq.yml#is-there-a-limit-to-the-number-of-partial-document-update-operations-)
-| For Operation(`PATCH_OPERATION_INDEX`): Index(`ARRAY_INDEX`) to operate on is out of array bounds | The index of array element to be patched is out of bounds 
-| For Operation(`PATCH_OPERATION_INDEX`)): Node(`PATH`) to be replaced has been removed earlier in the transaction.| The path you're trying to patch doesn't exist.
-| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) to be removed is absent. Note: it may also have been removed earlier in the transaction.  | The path you're trying to patch doesn't exist.
-| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) to be replaced is absent. | The path you're trying to patch doesn't exist.
-| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) isn't a number.| Increment operation can only work on integer and float. For more information, see: [Supported Operations](partial-document-update.md#supported-operations)
-| For Operation(`PATCH_OPERATION_INDEX`): Add Operation can only create a child object of an existing node(array or object) and can't create path recursively, no path found beyond: `PATH`. | Child paths can be added to an object or array node type. Also, to create `n`th child, `n-1`th child should be present 
-| For Operation(`PATCH_OPERATION_INDEX`): Given Operation can only create a child object of an existing node(array or object) and can't create path recursively, no path found beyond: `PATH`. | Child paths can be added to an object or array node type. Also, to create `n`th child, `n-1`th child should be present 
+| Invalid patch request: check syntax of patch specification. | The patch operation syntax is invalid. For more information, see [the Partial Document Update specification](partial-document-update.md#rest-api-reference-for-partial-document-update). |
+| Invalid patch request: Can't patch system property `SYSTEM_PROPERTY`. | System-generated properties like `_id`, `_ts`, `_etag`, `_rid` aren't modifiable using a patch operation. For more information, see [Partial Document Update FAQs](partial-document-update-faq.yml#is-partial-document-update-supported-for-system-generated-properties-). |
+| The number of patch operations can't exceed 10. | There's a limit of 10 patch operations that can be added in a single patch specification. For more information, see [Partial Document Update FAQs](partial-document-update-faq.yml#is-there-a-limit-to-the-number-of-partial-document-update-operations-). |
+| For Operation(`PATCH_OPERATION_INDEX`): Index(`ARRAY_INDEX`) to operate on is out of array bounds. | The index of array element to be patched is out of bounds. |
+| For Operation(`PATCH_OPERATION_INDEX`)): Node(`PATH`) to be replaced has been removed earlier in the transaction. | The path you're trying to patch doesn't exist. |
+| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) to be removed is absent. Note: it might also have been removed earlier in the transaction. | The path you're trying to patch doesn't exist. |
+| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) to be replaced is absent. | The path you're trying to patch doesn't exist. |
+| For Operation(`PATCH_OPERATION_INDEX`): Node(`PATH`) isn't a number. | Increment operation can only work on integer and float. For more information, see: [Supported Operations](partial-document-update.md#supported-operations). |
+| For Operation(`PATCH_OPERATION_INDEX`): Add Operation can only create a child object of an existing node (array or object) and can't create path recursively, no path found beyond: `PATH`. | Child paths can be added to an object or array node type. Also, to create `n`th child, `n-1`th child should be present. |
+| For Operation(`PATCH_OPERATION_INDEX`): Given Operation can only create a child object of an existing node(array or object) and can't create path recursively, no path found beyond: `PATH`. | Child paths can be added to an object or array node type. Also, to create `n`th child, `n-1`th child should be present. |
 
 ## Next steps
 
-- Review the conceptual overview of [Partial Document Update](partial-document-update.md)
+- [Partial Document Update in Azure Cosmos DB](partial-document-update.md)
+- [Frequently asked questions about Partial Document Update in Azure Cosmos DB](partial-document-update-faq.yml)