A newer version of this documentation is available.

View Latest

Updating and creating documents

This section shows how to update documents in Couchbase: using a Couchbase SDK, or through the cbc command line utility.
upsert(docid, document)
insert(docid, document)
replace(docid, document)

The first step in using a database involves storing data into it.

In Couchbase, documents are typically updated using one of the upsert, insert, and replace methods. These methods will all write a JSON document with a given document ID (key) to the database. The update methods differ in behavior in respect to the existing state of the document:

  • insert will only create the document if the given ID is not found within the database.

  • replace will only replace the document if the given ID already exists within the database.

  • upsert will always replace the document, ignoring whether the ID has already existed or not.

Since Couchbase’s KV store may be thought of as a distributed hashmap or dictionary, the following code samples are explanatory of Couchbase’ update operations


def insert(doc_id, value):
    if doc_id not in KV_STORE:
        KV_STORE[doc_id] = value
        raise KeyAlreadyExists()

def replace(doc_id, value):
    if doc_id in KV_STORE:
        KV_STORE[doc_id] = value
        raise KeyNotFound()

def upsert(doc_id, value):
    KV_STORE[doc_id] = value

Document IDs

Document IDs are assigned by application. A valid document ID must:

  • Conform to UTF-8 encoding

  • Be no longer than 250 bytes

    Note the difference between bytes and characters. Most non-Latin characters occupy more than a single byte

You are free to choose any ID for your document, so long as they conform to the above restrictions. Unlike some other database, Couchbase does not automatically generate IDs for you (but see [counter pattern]).

Updating documents via an SDK

Couchbase SDKs feature APIs reflecting the different ways to update documents.

Any update operation requires the document itself and document’s ID as input.

cb.upsert('docid', {'property': 'value'})
cb.insert('docid', {'property': 'value'})
cb.replace('docid', {'property': 'value'})

Examples of these operations in other SDKs:

node.js | Java | Go | .NET | C | Python

Document format

Most SDKs will automatically convert the document to JSON before storing it on the server (and will return an error if the document cannot be converted to JSON). Additional options are available if you wish to store non-JSON data. Refer to the documentation of the SDK you are using for more details on how to store JSON and non-JSON values.

Additional options

  • TTL or Expiry value which will instruct the server to delete the document after a given amount of time. This option is useful for transient data (such as sessions). By default documents do not expire. See TTL for more information on expiration.

  • CAS value to protect against concurrent updates to the same document. See CAS for a description on how to use CAS values in your application.

  • Persistence and replication requirements.

Return values

If an update completed successfully, a success indicator along with the document’s current CAS value is returned.

SDK-specific documentation

SDK-Specific documentation about creating documents may be found below: Python, Ruby, C, node.js, .NET, Java, Go

Updating documents via the command line

Documents may be updated using the cbc utility.

The following examples assume the cbc command is being executed on one of the cluster nodes. If run on another machine, refer to the documentation to see how to specify the cluster address.
# When storing JSON data using cbc, ensure it is properly quoted for your shell:
$ cbc create docid -V '{"json":"value"}' -M upsert
docid               Stored. CAS=0x8234c3c0f213