A newer version of this documentation is available.

View Latest
February 16, 2025
+ 12

How to update documents in Couchbase.
This guide is for Couchbase Server.

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 database. To restore your sample data, remove and reinstall the travel sample data. 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.

  1. Create a JSON document containing the updated data.

  2. 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
{ "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
Result
console
hotel-123 Stored. CAS=0x16bd48617f9d0000 SYNCTOKEN=500,228620113724555,292

For further details, refer to cbc(1).

Replacing a Document

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

  1. Update a JSON document with some new data.

  2. 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
{ "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
Result
console
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).

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.

  1. Connect to the cbc-subdoc interactive shell.

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

  3. 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
cbc-subdoc -u Administrator -P password -U couchbase://localhost/travel-sample subdoc> dict-upsert airport_1254 --path pets_ok=true
Result
console
airport_1254 CAS=0x16be23af9f630000 0. Size=0, RC=LCB_SUCCESS (0)

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

Key-Value Operations with SDKs:

Sub-Document operations with SDKs: