March 23, 2025
+ 12
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:

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.

  1. If you haven’t 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 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
console
╭───┬───────────┬─────────┬────────┬──────────┬─────────╮ │ # │ processed │ success │ failed │ failures │ cluster │ ├───┼───────────┼─────────┼────────┼──────────┼─────────┤ │ 0 │ 1 │ 1 │ 0 │ │ capella │ ╰───┴───────────┴─────────┴────────┴──────────┴─────────╯

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

Replacing a Document

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

  1. If you haven’t 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.

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 │ ╰───┴───────────┴─────────┴────────┴──────────┴─────────╯
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.

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. If you haven’t 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.

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 further details, refer to upsert for filters or update for filters in the Nushell documentation.

Key-Value Operations with SDKs:

Sub-Document operations with SDKs: