Update Documents

Capella Operational

how-to

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

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) — developer preview
SDK Clients

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 for details.

Upserting a Document

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

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Create a structured JSON object containing the updated data.
Use doc upsert to update the document.

If the document doesn’t exist, Couchbase Capella creates a new document.

The example below updates the existing document hotel-123.

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

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

For further details, refer to Mutating in the Couchbase Shell documentation.

Use the UpsertAsync() method to update a document in the database. If it doesn’t exist, Couchbase Capella creates 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 View button to see 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 Capella creates 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 View button to see 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 Capella creates 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 View button to see 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 Capella creates 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 View button to see this code in context.

For further details, refer to Collection.

Replacing a Document

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

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Create a structured JSON object containing the new data.
Use doc replace to update the document.

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

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

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

If the document cannot be found, Couchbase Shell returns a Key not found error.

For further details, refer to Mutating in the Couchbase Shell documentation.

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.

// 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 View button to see 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.

// 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 View button to see 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.

// 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 View button to see 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.

# 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 View button to see 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.

cbsh
.NET
Java
Node.js
Python

If you haven’t already done so, use cb-env to set the bucket, scope, and collection where the document is stored.
Use the doc get command to retrieve a document by ID.
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.
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.

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

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

For further details, refer to upsert for filters or update for filters in the Nushell documentation.

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.

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 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.

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 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.

const mutateInResult = await hotelCollection.mutateIn('hotel-123', [
  couchbase.MutateInSpec.upsert('pets_ok', true),
])
console.log('CAS:', mutateInResult.cas)

Click the View button to see 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.

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 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

Update Documents

Introduction

Upserting a Document

Replacing a Document

Updating a Sub-Document

Related Links