Updating Data
- how-to
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:
{
"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:
cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
--scope='inventory' \
--collection='hotel' \
--mode upsert hotel-123 <./tmp/hotel-123.json
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
.
// 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
.
// 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
.
// 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
.
# 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:
{
"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:
cbc create -u Administrator -P password -U couchbase://localhost/travel-sample \
--scope='inventory' \
--collection='hotel' \
--mode replace hotel-123 <./tmp/hotel-123.json
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’sCAS
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
.
// 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’sCAS
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
.
// 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’sCAS
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
.
// 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’sCAS
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
.
# 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 thereplace
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.
cbc-subdoc -u Administrator -P password -U couchbase://localhost/travel-sample
subdoc> dict-upsert airport_1254 --path pets_ok=true
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 containingMutateInSpec
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.
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 ofMutateInSpec
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.
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 ofMutateInSpec
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.
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 ofMutateInSpec
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.
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.