Skip to content

Commit c8ed11b

Browse files
denreadenrea
authored
Merge pull request #233157 from seesharprun/cosmos-partial-code-sample
Cosmos DB | Revamp and review partial document update articles
2 parents 3d2d9f9 + 5b5b3ba commit c8ed11b

File tree

2 files changed

+50
-33
lines changed

2 files changed

+50
-33
lines changed

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

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
---
2-
title: Get started with Azure Cosmos DB Partial Document Update
3-
description: Learn how to use Partial Document Update with .NET, Java, and Node SDKs for Azure Cosmos DB with these examples.
2+
title: Get started with partial document update
3+
titleSuffix: Azure Cosmos DB for NoSQL
4+
description: Learn how to use the partial document update feature with the .NET, Java, and Node SDKs for Azure Cosmos DB for NoSQL.
5+
ms.author: sidandrews
46
author: seesharprun
57
ms.service: cosmos-db
68
ms.subservice: nosql
79
ms.topic: how-to
8-
ms.date: 03/06/2023
9-
ms.author: sidandrews
10+
ms.date: 04/03/2023
1011
ms.custom: ignite-fall-2021, ignite-2022
1112
---
1213

1314
# Get started with Azure Cosmos DB Partial Document Update
15+
1416
[!INCLUDE[NoSQL](includes/appliesto-nosql.md)]
1517

1618
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.
@@ -22,6 +24,13 @@ This article links to code samples for the following scenarios:
2224
- Use conditional patch syntax based on filter predicate
2325
- Run patch operation as part of a transaction
2426

27+
## Prerequisites
28+
29+
- An existing Azure Cosmos DB account.
30+
- If you have an Azure subscription, [create a new account](nosql/how-to-create-account.md?tabs=azure-portal).
31+
- If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
32+
- Alternatively, you can [try Azure Cosmos DB free](try-free.md) before you commit.
33+
2534
## [.NET](#tab/dotnet)
2635

2736
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).
@@ -48,9 +57,10 @@ Support for Partial Document Update (Patch API) in the [Azure Cosmos DB .NET v3
4857
```csharp
4958
List<PatchOperation> operations = new ()
5059
{
51-
PatchOperation.Add($"/color", "silver"),
60+
PatchOperation.Add("/color", "silver"),
5261
PatchOperation.Remove("/used"),
53-
PatchOperation.Increment("/price", 50.00)
62+
PatchOperation.Increment("/price", 50.00),
63+
PatchOperation.Add("/tags/-", "featured-bikes")
5464
};
5565

5666
ItemResponse<Product> response = await container.PatchItemAsync<Product>(
@@ -375,5 +385,4 @@ Here's some common errors that you might encounter while using this feature:
375385

376386
## Next steps
377387

378-
- [Partial Document Update in Azure Cosmos DB](partial-document-update.md)
379388
- [Frequently asked questions about Partial Document Update in Azure Cosmos DB](partial-document-update-faq.yml)

‎articles/cosmos-db/partial-document-update.md

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
---
22
title: Partial document update
3-
titleSuffix: Azure Cosmos DB
4-
description: Learn how to conditionally modify a document using the partial document update feature in Azure Cosmos DB.
3+
titleSuffix: Azure Cosmos DB for NoSQL
4+
description: Learn how to conditionally modify a document using the partial document update feature in Azure Cosmos DB for NoSQL.
5+
ms.author: sidandrews
56
author: seesharprun
67
ms.service: cosmos-db
78
ms.subservice: nosql
89
ms.topic: conceptual
9-
ms.date: 04/29/2022
10-
ms.author: sidandrews
10+
ms.date: 04/03/2023
1111
ms.custom: ignite-fall-2021, ignite-2022
1212
---
1313

@@ -30,40 +30,48 @@ An example target JSON document:
3030

3131
```json
3232
{
33-
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
34-
"name": "R-410 Road Bicycle",
35-
"price": 455.95,
36-
"inventory": {
37-
"quantity": 15
38-
},
39-
"used": false,
40-
"categoryId": "road-bikes"
33+
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
34+
"name": "R-410 Road Bicycle",
35+
"price": 455.95,
36+
"inventory": {
37+
"quantity": 15
38+
},
39+
"used": false,
40+
"categoryId": "road-bikes",
41+
"tags": [
42+
"r-series"
43+
]
4144
}
4245
```
4346

4447
A JSON Patch document:
4548

4649
```json
4750
[
48-
{ "op": "add", "path": "/color", "value": "silver" },
49-
{ "op": "remove", "path": "/used" },
50-
{ "op": "set", "path": "/price", "value": 355.45 }
51-
{ "op": "incr", "path": "/inventory/quantity", "value": 10 }
51+
{ "op": "add", "path": "/color", "value": "silver" },
52+
{ "op": "remove", "path": "/used" },
53+
{ "op": "set", "path": "/price", "value": 355.45 }
54+
{ "op": "incr", "path": "/inventory/quantity", "value": 10 },
55+
{ "op": "add", "path": "/tags/-", "value": "featured-bikes" }
5256
]
5357
```
5458

5559
The resulting JSON document:
5660

5761
```json
5862
{
59-
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
60-
"name": "R-410 Road Bicycle",
61-
"price": 355.45,
62-
"inventory": {
63-
"quantity": 25
64-
},
65-
"categoryId": "road-bikes",
66-
"color": "silver"
63+
"id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
64+
"name": "R-410 Road Bicycle",
65+
"price": 355.45,
66+
"inventory": {
67+
"quantity": 25
68+
},
69+
"categoryId": "road-bikes",
70+
"color": "silver",
71+
"tags": [
72+
"r-series",
73+
"featured-bikes"
74+
]
6775
}
6876
```
6977

@@ -90,7 +98,7 @@ Partial document update feature supports the following modes of operation. Refer
9098

9199
- **Multi-document patch**: Multiple documents within the same partition key can be patched as a [part of a transaction](transactional-batch.md). This multi-document transaction is committed only if all the operations succeed in the order they're described. If any operation fails, the entire transaction is rolled back.
92100

93-
- **Conditional Update**: For the aforementioned modes, it's also possible to add a SQL-like filter predicate (for example, `from c where c.taskNum = 3`) such that the operation fails if the pre-condition specified in the predicate isn't satisfied.
101+
- **Conditional Update**: For the aforementioned modes, it's also possible to add a SQL-like filter predicate (for example, `from c where c.taskNum = 3`) such that the operation fails if the precondition specified in the predicate isn't satisfied.
94102

95103
- You can also use the bulk APIs of supported SDKs to execute one or more patch operations on multiple documents.
96104

@@ -172,7 +180,7 @@ Different clients issue Patch operations concurrently across different regions:
172180

173181
:::image type="content" source="./media/partial-document-update/patch-multi-region-conflict-resolution.png" alt-text="An image that shows conflict resolution in concurrent multi-region partial update operations." border="false" lightbox="./media/partial-document-update/patch-multi-region-conflict-resolution.png":::
174182

175-
Since Patch requests were made to non-conflicting paths within the document, these requests are conflict resolved automatically and transparently (as opposed to Last Writer Wins at a document level).
183+
Since Patch requests were made to nonconflicting paths within the document, these requests are conflict resolved automatically and transparently (as opposed to Last Writer Wins at a document level).
176184

177185
The client will see the following document after conflict resolution:
178186

0 commit comments

Comments
 (0)