A newer version of this documentation is available.

Updating Data

how-to

March 23, 2025

+ 12

How to update documents in Couchbase.

Introduction

Couchbase Server 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:

Please note that the examples in this guide will alter the data in your sample buckets. To restore your sample data, remove and reinstall the travel-sample bucket. Refer to Sample Buckets for details.

Upserting a Document

To update a document, or create the document if it doesn’t exist, perform an upsert operation.

cbc
.NET
Java
Node.js
Python

Create a JSON document containing the updated data.
Use the cbc create command with --mode upsert to update the document in the database. If it doesn’t exist, Couchbase will simply create a new document.

The example below updates the existing document hotel-123.

First, create the updated file hotel-123.json and store it the tmp directory:

hotel-123

json
Copy
{
  "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."
}

Now insert the document:

shell
ViewCopy
cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
	--scope='inventory' \
	--collection='hotel' \
	--mode upsert hotel-123 <./tmp/hotel-123.json

Result

console
Copy
hotel-123            Stored. CAS=0x16bd48617f9d0000
                     SYNCTOKEN=500,228620113724555,292

For further details, refer to cbc(1).

Use the UpsertAsync() method to update a document in the database. If it doesn’t exist, Couchbase will simply create a new document.

The example below updates the existing document hotel-123.

csharp
ViewCopy
// 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 GitHub button to view this code in context.

For further details, refer to CollectionExtensions.

Use the upsert() method to update a document in the database. If it doesn’t exist, Couchbase will simply create a new document.

The example below updates the existing document hotel-123.

java
ViewCopy
// 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 GitHub button to view this code in context.

For further details, refer to Collection.

Use the upsert() function to update a document in the database. If it doesn’t exist, Couchbase will simply create a new document.

The example below updates the existing document hotel-123.

nodejs
ViewCopy
// Update or create a document in the hotel collection.
const upsertResult = await hotelCollection.upsert('hotel-123', document)

// Print the result's CAS metadata to the console.
console.log('CAS:', upsertResult.cas)

Click the GitHub button to view this code in context.

For further details, refer to Collection.

Use the upsert() function to update a document in the database. If it doesn’t exist, Couchbase will simply create a new document.

The example below updates the existing document hotel-123.

python
ViewCopy
# 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 GitHub button to view this code in context.

For further details, refer to Collection.

Replacing a Document

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

cbc
.NET
Java
Node.js
Python

Update a JSON document with some new data.
Use the cbc create command with --mode replace to update a document.

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

First, create the updated file hotel-123.json and store it the tmp directory:

hotel-123

json
Copy
{
  "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."
}

Now insert the document:

shell
ViewCopy
cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
	--scope='inventory' \
	--collection='hotel' \
	--mode replace hotel-123 <./tmp/hotel-123.json

Result

console
Copy
hotel-123            Stored. CAS=0x16bd486ce6250000
                     SYNCTOKEN=500,228620113724555,293

If the document cannot be found, cbc will return a LCB_ERR_DOCUMENT_NOT_FOUND error.

For further details, refer to cbc(1).

Fetch an existing document and change some of its data.
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
ViewCopy
// 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}");

If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.

Click the GitHub button to view this code in context.

For further details, refer to CollectionExtensions.

Fetch an existing document and change some of its data.
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
ViewCopy
// 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());

If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.

Click the GitHub button to view this code in context.

For further details, refer to Collection.

Fetch an existing document and change some of its data.
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
ViewCopy
// Fetch an existing hotel document.
getResult = await hotelCollection.get('hotel-123')
const existingDoc = getResult.content

// Get the current CAS value.
const currentCas = getResult.cas
console.log('Current CAS:', currentCas)

// Add a new review to the reviews array.
existingDoc['reviews'].push({
  content: 'This hotel was cozy, conveniently located and clean.',
  author: "Carmella O'Keefe",
  date: new Date().toISOString(),
})

// Update the document with new data and pass the current CAS value.
const replaceResult = await hotelCollection.replace(
  'hotel-123',
  existingDoc
)

// Print the new CAS value.
console.log('New CAS:', replaceResult.cas)

If the document doesn’t exist, the SDK will return a DocumentNotFoundError error.

Click the GitHub button to view this code in context.

For further details, refer to Collection.

Fetch an existing document and change some of its data.
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
ViewCopy
# 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)

If the document doesn’t exist, the SDK will return a DocumentNotFoundException error.

Click the GitHub button to view this code in context.

For further details, refer to Collection.

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 is required for your application.

cbc-subdoc
.NET
Java
Node.js
Python

Connect to the cbc-subdoc interactive shell.
Use the dict-upsert command to update/add a field in a document, or use the replace command if you require the field to exist.
Pass the field to update/add and its value with the --path argument.

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

console
Copy
cbc-subdoc -u Administrator -P password -U couchbase://localhost/travel-sample
subdoc> dict-upsert airport_1254 --path pets_ok=true

Result

console
Copy
airport_1254         CAS=0x16be23af9f630000
0. Size=0, RC=LCB_SUCCESS (0)

For further details, refer to cbc-subdoc(1).

Call the MutateInAsync() method, which takes a document ID and an IEnumerable containing MutateInSpec objects.
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
ViewCopy
var mutateInResult = await hotelCollection.MutateInAsync("hotel-123",
	specs => specs.Upsert("pets_ok", true)
);
Console.WriteLine($"Cas: {mutateInResult.Cas}");

Click the GitHub button to view this code in context.

For further details, refer to CollectionExtensions.

Call the mutateIn() method, which takes a document ID and an array of MutateInSpec objects.
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
ViewCopy
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 GitHub button to view this code in context.

For further details, refer to Collection.

Call the mutateIn() method, which takes a document ID and an array of MutateInSpec objects.
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
ViewCopy
const mutateInResult = await hotelCollection.mutateIn('hotel-123', [
  couchbase.MutateInSpec.upsert('pets_ok', true),
])
console.log('CAS:', mutateInResult.cas)

Click the GitHub button to view this code in context.

For further details, refer to Collection.

Call the mutate_in() function, which takes a document ID and a list of MutateInSpec objects.
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
ViewCopy
mutate_in_result = hotel_collection.mutate_in(
    "hotel-123", [subdocument.upsert("pets_ok", True)]
)
print("CAS:", mutate_in_result.cas)

Click the GitHub button to view this code in context.

For further details, refer to Collection.

Key-Value Operations with SDKs:

C | .NET | Go | Java | Node.js | PHP | Python | Ruby | Scala

Sub-Document operations with SDKs:

C | .NET | Go | Java | Node.js | PHP | Python | Ruby | Scala

Updating Data

Introduction

Upserting a Document

Replacing a Document

Updating a Sub-Document

Related Links