---
title: Update Documents
description: How to update documents with a command line tool or an SDK.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbaselabs/docs-devex/edit/capella/modules/guides/pages/updating-data.adoc
  xref: xref:cloud:guides:updating-data.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/cloud/guides/updating-data.html)

# Update Documents

> How to update documents with a command line tool or an SDK. 

## [](#introduction)Introduction

Couchbase Capella allows you to update data within a document by ID using either an upsert or a replace operation. An upsert operation will update or create a full document with the given data. A replace operation, on the other hand, will only replace a document if it exists within the database.

Read the following for further information about the clients available:

* [Couchbase Shell (cbsh)](https://couchbase.sh/docs/)
* [SDK Clients](../../home/sdk.md)

> [!WARNING]
> Please note that the examples in this guide will alter the data in your sample database. To restore your sample data, remove and reinstall the travel sample data. Refer to [Import Data with the Capella UI](../clusters/data-service/import-data-documents.md) for details.

## [](#upserting-a-document)Upserting a Document

To update a document, or create the document if it does not exist, perform an upsert operation.

* cbsh
* .NET
* Java
* Node.js
* Python

1. If you have not already done so, use `cb-env` to set the bucket, scope, and collection where the document is stored.
2. Create a structured JSON object containing the updated data.
3. Use `doc upsert` to update the document.

If the document does not exist, Couchbase Capella creates a new document.

---

The example below updates the existing document `hotel-123`.

```sh
cb-env bucket travel-sample
cb-env scope inventory
cb-env collection hotel

doc upsert hotel-123 {
  "id": 123,
  "name": "Medway Youth Hostel",
  "address": "Capstone Road, ME7 3JE",
  "url": "http://www.yha.org.uk",
  "country": "United Kingdom",
  "city": "Medway",
  "state": null,
  "vacancy": true,
  "description": "40 bed summer hostel about 3 miles from Gillingham."
}
```

Result

```console
╭───┬───────────┬─────────┬────────┬──────────┬─────────╮
│ # │ processed │ success │ failed │ failures │ cluster │
├───┼───────────┼─────────┼────────┼──────────┼─────────┤
│ 0 │         1 │       1 │      0 │          │ capella │
╰───┴───────────┴─────────┴────────┴──────────┴─────────╯
```

For more information, see [Mutating](https://couchbase.sh/docs/#%5Fmutating) in the Couchbase Shell documentation.

Use the `UpsertAsync()` method to update a document in the database. If it does not exist, Couchbase Capella creates a new document.

---

The example below updates the existing document `hotel-123`.

```csharp
// Update or create a document in the hotel collection.
var upsertResult = await hotelCollection.UpsertAsync("hotel-123", document);

// Print the result's CAS metadata to the console.
Console.WriteLine($"Cas: {upsertResult.Cas}");
```

Click the  View button to see this code in context.

For more information, see [CollectionExtensions](https://docs.couchbase.com/sdk-api/couchbase-net-client/api/Couchbase.KeyValue.CollectionExtensions.html).

Use the `upsert()` method to update a document in the database. If it does not exist, Couchbase Capella creates a new document.

---

The example below updates the existing document `hotel-123`.

```java
// Update or create a document in the hotel collection.
MutationResult upsertResult = hotelCollection.upsert("hotel-123", document);

// Print the result's CAS metadata to the console.
System.out.println("CAS:" + upsertResult.cas());
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/Collection.html).

Use the `upsert()` function to update a document in the database. If it does not exist, Couchbase Capella creates a new document.

---

The example below updates the existing document `hotel-123`.

```nodejs
Unresolved include directive in modules/guides/pages/updating-data.adoc - include::nodejs-sdk:hello-world:example$kv-hello-world-scoped.js[]
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-node-client/classes/Collection.html).

Use the `upsert()` function to update a document in the database. If it does not exist, Couchbase Capella creates a new document.

---

The example below updates the existing document `hotel-123`.

```python
# Update or create a document in the hotel collection.
upsert_result = hotel_collection.upsert("hotel-123", document)

# Print the result's CAS metadata to the console.
print("CAS:", upsert_result.cas)
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-python-client/api/couchbase.html#collection-object).

## [](#replacing-a-document)Replacing a Document

To update a document that already exists, perform a replace operation.

* cbsh
* .NET
* Java
* Node.js
* Python

1. If you have not already done so, use `cb-env` to set the bucket, scope, and collection where the document is stored.
2. Create a structured JSON object containing the new data.
3. Use `doc replace` to update the document.

---

The example below adds a new entry to the `reviews` array in document `hotel-123`.

```sh
cb-env bucket travel-sample
cb-env scope inventory
cb-env collection hotel

doc replace hotel-123 {
  "id": 123,
  "name": "Medway Youth Hostel",
  "address": "Capstone Road, ME7 3JE",
  "url": "http://www.yha.org.uk",
  "geo": {
    "lat": 51.35785,
    "lon": 0.55818,
    "accuracy": "RANGE_INTERPOLATED"
  },
  "country": "United Kingdom",
  "city": "Medway",
  "state": null,
  "reviews": [
    {
      "content": "This was our 2nd trip here and we enjoyed it more than last year.",
      "author": "Ozella Sipes",
      "date": "2021-12-13T17:38:02.935Z"
    },
    {
      "content": "This hotel was cozy, conveniently located and clean.",
      "author": "Carmella O'Keefe",
      "date": "2021-12-13T17:38:02.974Z"
    }
  ],
  "vacancy": true,
  "description": "40 bed summer hostel about 3 miles from Gillingham."
}
```

Result

```console
╭───┬───────────┬─────────┬────────┬──────────┬─────────╮
│ # │ processed │ success │ failed │ failures │ cluster │
├───┼───────────┼─────────┼────────┼──────────┼─────────┤
│ 0 │         1 │       1 │      0 │          │ capella │
╰───┴───────────┴─────────┴────────┴──────────┴─────────╯
```

> [!NOTE]
> If the document cannot be found, Couchbase Shell returns a `Key not found` error.

For more information, see [Mutating](https://couchbase.sh/docs/#%5Fmutating) in the Couchbase Shell documentation.

1. Fetch an existing document and change some of its data.
2. Use the `ReplaceAsync()` function to update a document in Couchbase. To ensure data has not been modified before executing the replace operation, pass the document's `CAS` value to the method.

A new `CAS` value is provided in the returned `MutationResult` object.

---

The example below adds a new entry to the `reviews` array in document `hotel-123`.

```csharp
// Fetch an existing hotel document.
var getResult = await hotelCollection.GetAsync("hotel-123");
var existingDoc = getResult.ContentAs<JObject>();

// Get the current CAS value.
var currentCas = getResult.Cas;
Console.WriteLine($"Current Cas: {currentCas}");

// Add a new review to the reviews array.
var reviews = (JArray)existingDoc["reviews"];
reviews.Add(new JObject(
	new JProperty("content", "This hotel was cozy, conveniently located and clean."),
	new JProperty("author", "Carmella O'Keefe"),
	new JProperty("date", DateTime.UtcNow))
);

// Update the document with new data and pass the current CAS value. 
var replaceResult = await hotelCollection.ReplaceAsync("hotel-123", existingDoc, options =>
{
	options.Cas(currentCas);
});

// Print the new CAS value.
Console.WriteLine($"New Cas: {replaceResult.Cas}");
```

> [!NOTE]
> If the document does not exist, the SDK will return a `DocumentNotFoundException` error.

Click the  View button to see this code in context.

For more information, see [CollectionExtensions](https://docs.couchbase.com/sdk-api/couchbase-net-client/api/Couchbase.KeyValue.CollectionExtensions.html).

1. Fetch an existing document and change some of its data.
2. Use the `replace()` method to update a document in Couchbase. To ensure data has not been modified before executing the replace operation, pass the document's `CAS` value to the method.

A new `CAS` value is provided in the returned `MutationResult` object.

---

The example below adds a new entry to the `reviews` array in document `hotel-123`.

```java
// Fetch an existing hotel document
GetResult getResult = hotelCollection.get("hotel-123");
JsonObject existingDoc = getResult.contentAsObject();

// Get the current CAS value.
Long currentCas = getResult.cas();
System.out.println("Current CAS:" + currentCas);

// Add a new review to the reviews array.
existingDoc.getArray("reviews").add(JsonObject.create()
    .put("content", "This hotel was cozy, conveniently located and clean.")
    .put("author", "Carmella O'Keefe")
    .put("date", DateTimeFormatter.ISO_INSTANT.format(Instant.now())
  )
);

// Update the document with new data and pass the current CAS value. 
MutationResult replaceResult = hotelCollection.replace(
    "hotel-123",
    existingDoc,
    ReplaceOptions.replaceOptions().cas(currentCas)
);

// Print the new CAS value.
System.out.println("New CAS:" + replaceResult.cas());
```

> [!NOTE]
> If the document does not exist, the SDK will return a `DocumentNotFoundException` error.

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/Collection.html).

1. Fetch an existing document and change some of its data.
2. Use the `replace()` function to update a document in Couchbase. To ensure data has not been modified before executing the replace operation, pass the document's `CAS` value to the method.

A new `CAS` value is provided in the returned `MutationResult` object.

---

The example below adds a new entry to the `reviews` array in document `hotel-123`.

```nodejs
Unresolved include directive in modules/guides/pages/updating-data.adoc - include::nodejs-sdk:hello-world:example$kv-hello-world-scoped.js[]
```

> [!NOTE]
> If the document does not exist, the SDK will return a `DocumentNotFoundError` error.

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-node-client/classes/Collection.html).

1. Fetch an existing document and change some of its data.
2. Use the `replace()` function to update a document in Couchbase. To ensure data has not been modified before executing the replace operation, pass the document's `CAS` value to the method.

A new `CAS` value is provided in the returned `MutationResult` object.

---

The example below adds a new entry to the `reviews` array in document `hotel-123`.

```python
# Fetch an existing hotel document.
get_result = hotel_collection.get("hotel-123")
existing_doc = get_result.content_as[dict]

# Get the current CAS value.
current_cas = get_result.cas
print("Current CAS:", get_result.cas)

# Add a new review to the reviews array.
existing_doc["reviews"].append({
    "content": "This hotel was cozy, conveniently located and clean.",
    "author": "Carmella O'Keefe",
    "date": datetime.now().isoformat(),
})

# Update the document with new data and pass the current CAS value.
replace_result = hotel_collection.replace(
    "hotel-123", existing_doc, ReplaceOptions(cas=current_cas)
)
print("New CAS:", replace_result.cas)
```

> [!NOTE]
> If the document does not exist, the SDK will return a `DocumentNotFoundException` error.

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-python-client/api/couchbase.html#collection-object).

## [](#updating-a-sub-document)Updating a Sub-Document

To change a specific field inside a document, you can perform a Sub-Document operation. You can use either a Sub-Document upsert or replace operation depending on what's required for your application.

* cbsh
* .NET
* Java
* Node.js
* Python

1. If you have not already done so, use `cb-env` to set the bucket, scope, and collection where the document is stored.
2. Use the `doc get` command to retrieve a document by ID.
3. Pipe the document through the `upsert` filter to update or add the field containing the Sub-Document, or use the `update` filter if you require the field to exist.
4. Pipe the output, including the `id` and `content` fields, through the `doc replace` command to update the document.

---

The example below upserts a `pets_ok` field in document `hotel-123` and sets the value to true.

```sh
cb-env bucket travel-sample
cb-env scope inventory
cb-env collection hotel

doc get hotel-123 | upsert content.pets_ok true | doc replace
```

Result

```console
╭───┬───────────┬─────────┬────────┬──────────┬─────────╮
│ # │ processed │ success │ failed │ failures │ cluster │
├───┼───────────┼─────────┼────────┼──────────┼─────────┤
│ 0 │         1 │       1 │      0 │          │ capella │
╰───┴───────────┴─────────┴────────┴──────────┴─────────╯
```

For more information, see [upsert for filters](https://www.nushell.sh/commands/docs/upsert.html) or [update for filters](https://www.nushell.sh/commands/docs/update.html) in the Nushell documentation.

1. Call the `MutateInAsync()` method, which takes a document ID and an IEnumerable containing `MutateInSpec` objects.
2. Use a `MutateInSpec` object to specify the sub-operation to be performed within the lookup.

A `MutateInResult` object is returned, containing the result and metadata relevant to the Sub-Document update operation.

---

The example below upserts a `pets_ok` field in document `hotel-123` and sets the value to true.

```csharp
var mutateInResult = await hotelCollection.MutateInAsync("hotel-123",
	specs => specs.Upsert("pets_ok", true)
);
Console.WriteLine($"Cas: {mutateInResult.Cas}");
```

Click the  View button to see this code in context.

For more information, see [CollectionExtensions](https://docs.couchbase.com/sdk-api/couchbase-net-client/api/Couchbase.KeyValue.CollectionExtensions.html).

1. Call the `mutateIn()` method, which takes a document ID and an array of `MutateInSpec` objects.
2. Use a `MutateInSpec` object to specify the sub-operation to be performed within the lookup.

A `MutateInResult` object is returned, containing the result and metadata relevant to the Sub-Document update operation.

---

The example below upserts a `pets_ok` field in document `hotel-123` and sets the value to true.

```java
List<MutateInSpec> specs = Arrays.asList(MutateInSpec.upsert("pets_ok", true));

MutateInResult mutateInResult = hotelCollection.mutateIn("hotel-123", specs);
System.out.println("CAS:" + mutateInResult.cas());
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-java-client/com/couchbase/client/java/Collection.html).

1. Call the `mutateIn()` method, which takes a document ID and an array of `MutateInSpec` objects.
2. Use a `MutateInSpec` object to specify the sub-operation to be performed within the lookup.

A `MutateInResult` object is returned, containing the result and metadata relevant to the Sub-Document update operation.

---

The example below upserts a `pets_ok` field in document `hotel-123` and sets the value to true.

```nodejs
Unresolved include directive in modules/guides/pages/updating-data.adoc - include::nodejs-sdk:hello-world:example$kv-hello-world-scoped.js[]
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-node-client/classes/Collection.html).

1. Call the `mutate_in()` function, which takes a document ID and a list of `MutateInSpec` objects.
2. Use a `MutateInSpec` object to specify the sub-operation to be performed within the lookup.

A `MutateInResult` object is returned, containing the result and metadata relevant to the Sub-Document get operation.

---

The example below upserts a `pets_ok` field in document `hotel-123` and sets the value to true.

```python
mutate_in_result = hotel_collection.mutate_in(
    "hotel-123", [subdocument.upsert("pets_ok", True)]
)
print("CAS:", mutate_in_result.cas)
```

Click the  View button to see this code in context.

For more information, see [Collection](https://docs.couchbase.com/sdk-api/couchbase-python-client/api/couchbase.html#collection-object).

## [](#related-links)Related Links

Key-Value Operations with SDKs:

* [C](../../c-sdk/current/howtos/kv-operations.md)| [C++](../../cxx-sdk/current/howtos/kv-operations.md)| [.NET](../../dotnet-sdk/current/howtos/kv-operations.md)| [Go](../../go-sdk/current/howtos/kv-operations.md)| [Java](../../java-sdk/current/howtos/kv-operations.md)| [Kotlin](../../kotlin-sdk/current/howtos/kv-operations.md)| [Node.js](../../nodejs-sdk/current/howtos/kv-operations.md)| [PHP](../../php-sdk/current/howtos/kv-operations.md)| [Python](../../python-sdk/current/howtos/kv-operations.md)| [Ruby](../../ruby-sdk/current/howtos/kv-operations.md)| [Rust](../../rust-sdk/current/howtos/kv-operations.md)| [Scala](../../scala-sdk/current/howtos/kv-operations.md)

Sub-Document operations with SDKs:

* [C](../../c-sdk/current/howtos/subdocument-operations.md)| [C++](../../cxx-sdk/current/howtos/subdocument-operations.md)| [.NET](../../dotnet-sdk/current/howtos/subdocument-operations.md)| [Go](../../go-sdk/current/howtos/subdocument-operations.md)| [Java](../../java-sdk/current/howtos/subdocument-operations.md)| Kotlin | [Node.js](../../nodejs-sdk/current/howtos/subdocument-operations.md)| [PHP](../../php-sdk/current/howtos/subdocument-operations.md)| [Python](../../python-sdk/current/howtos/subdocument-operations.md)| [Ruby](../../ruby-sdk/current/howtos/subdocument-operations.md)| [Rust](../../rust-sdk/current/howtos/subdocument-operations.md)| [Scala](../../scala-sdk/current/howtos/subdocument-operations.md)