Key Value Operations

how-to

Documents

A document refers to an entry in the database (other databases may refer to the same concept as a row). A document has an ID (primary key in other databases), which is unique to the document and by which it can be located. The document also has a value which contains the actual application data. See the concept guide to Documents for a deeper dive into documents in the Couchbase Data Platform. Or read on, for a hands-on introduction to working with documents from the Node.js SDK.

CRUD Operations

The core interface to Couchbase Server is simple KV operations on full documents. Make sure you’re familiar with the basics of authorization and connecting to a Cluster from the Start Using the SDK section. We’re going to expand on the short Upsert example we used there, adding options as we move through the various CRUD operations. Here is the Insert operation at its simplest:

Insert

const result = await collection.insert(key, document);

Options may be added to operations:

Insert (with options)

const result = await collection.insert(key, document,
    { timeout: 10000 } // 10 seconds
);

Setting a Compare and Swap (CAS) value is a form of optimistic locking - dealt with in depth in the CAS page. Here we just note that the CAS is a value representing the current state of an item; each time the item is modified, its CAS changes. The CAS value is returned as part of a document’s metadata whenever a document is accessed.

timeout is an optional parameter which is represented in milliseconds. Timeout sets the timeout value for the operation. We will add to these options for the Replace example:

const result = await collection.replace(key,
    document,
    { cas: cas, expiry: 60, timeout: 5000 }
);

Expiration sets an explicit time to live (TTL) for a document. We’ll discuss modifying Expiration in more details below. For a discussion of item (Document) vs Bucket expiration, see the Expiration Overview page.

Durability

let result = await collection.upsert(key, document,
    {
        expiry: 60,
        persist_to: 1,
        replicate_to: 0, // cannot replicate on single node
        timeout: 5000
    }
);

Here, we have added Durability options, namely persistTo and replicateTo. In Couchbase Server releases before 6.5, Durability was set with these two options — see the 6.0 Durability documentation — covering how many replicas the operation must be propagated to and how many persisted copies of the modified record must exist. If a version of Couchbase Server lower than 6.5 is being used then the application can fall-back to this 'client verified' durability.

If 6.5 or above is being used, you can take advantage of the Durable Write feature, in which Couchbase Server will only return success to the SDK after the requested replication level has been achieved. The three replication levels are:

Majority - The server will ensure that the change is available in memory on the majority of configured replicas.
MajorityAndPersistToActive - Majority level, plus persisted to disk on the active node.
PersistToMajority - Majority level, plus persisted to disk on the majority of configured replicas.

The options are in increasing levels of safety. Note that nothing comes for free - for a given node, waiting for writes to storage is considerably slower than waiting for it to be available in-memory. These trade offs, as well as which settings may be tuned, are discussed in the durability page.

The following example demonstrates using the newer durability features available in Couchbase server 6.5 onwards.

let result = await collection.upsert(key, document,
    {
        expiry: 60,  // 60 seconds,
        durabilityLevel: couchbase.DurabilityLevel.None, // Majority etc.
        timeout: 5000
    } // 5 seconds
);

To stress, durability is a useful feature but should not be the default for most applications, as there is a performance consideration, and the default level of safety provided by Couchbase will be reasonable for the majority of situations.

Sub-Document Operations

All of these operations involve fetching the complete document from the Cluster. Where the number of operations or other circumstances make bandwidth a significant issue, the SDK can work on just a specific path of the document with Sub-Document Operations.

Retrieving full documents

Using the get() method with the document key can be done in a similar fashion to the other operations:

const result = await collection.get(key);
document = result.value;

Timeout can also be set - as in the earlier Insert example:

Get (with options)

const result = await collection.get(key, { timeout: 1000 });
document = result.value;

Removing

When removing a document, you will have the same concern for durability as with any additive modification to the Bucket:

Remove (with options)

const result = await collection.remove(key,
    {
        cas: cas,
        persist_to: 0,  // non-zero gives "not implemented"
        replicate_to: 0, // cannot replicate on single node
        timeout: 5000
    }
);

Expiration / TTL

By default, Couchbase documents do not expire, but transient or temporary data may be needed for user sessions, caches, or other temporary documents. Using touch(), you can set expiration values on documents to handle transient data:

const result = await collection.touch(key, 100); // 100 seconds

A network timeout can be set with the options, in the same fashion as earlier examples on this page:

const result = await collection.touch(key, 100,  // 100 seconds
    { timeout: 5000 } // 5 seconds
);

If the absolute value of the expiry is less than 30 days (such as 60 * 60 * 24 * 30), it is considered an offset. If the value is greater, it is considered an absolute time stamp. For more on expiration see the expiration section of our documents discussion doc.

Atomic Counters

The value of a document can be increased or decreased atomically using binary().increment() and binary().decrement().

Increment & Decrement are considered part of the ‘binary’ API and as such may still be subject to change.

Increment

// increment binary value by 1
const result = await collection.binary().increment(binValKey, 1);

Increment (with options)

// increment binary value by 1, if binValKey doesn’t exist, seed it at 1000
const result = await collection.binary().increment(binValKey, 1, {
    initial: 1000,
    timeout: 5000
});

Decrement

// decrement binary value by 1
const result = await collection.binary().decrement(binValKey, 1);

Decrement (with options)

// decrement binary value by 1, if binValKey doesn’t exist, seed it at 1000
const result = await collection.binary().decrement(binValKey, 1,
    {
        initial: 1000,
        timeout: 5000
    },
);

Setting the document expiry time only works when a document is created, and it is not possible to update the expiry time of an existing counter document with the Increment method — to do this during an increment, use with the Touch() method.

Atomicity Across Data Centers

If you are using Cross Data Center Replication (XDCR), be sure to avoid modifying the same counter in more than one datacenter. If the same counter is modified in multiple datacenters between replications, the counter will no longer be atomic, and its value can change in unspecified ways.

A counter must be incremented or decremented by only a single datacenter. Each datacenter must have its own set of counters that it uses — a possible implementation would be including a datacenter name in the counter document ID.

Scoped KV Operations

It is possible to perform scoped key value operations on named Collections with Couchbase Server release, 7.0.

Here is an example showing an upsert in the users collection, which lives in the travel-sample.tenant_agent_00 keyspace:

const sampleOptions = { username: 'Administrator', password: 'password' };
const sampleCluster = new couchbase.Cluster("localhost", sampleOptions);
const sampleBucket = sampleCluster.bucket("travel-sample");
const sampleScope = sampleBucket.scope("tenant_agent_00");
sampleColl = sampleScope.collection("users");

[data-source-url=https://github.com/couchbase/docs-sdk-nodejs/blob/9af751ac9bbfd6ff0c0da845b4e28563af08cf88/modules/devguide/examples/nodejs/kv-operations.js#L514-L515]
let collDocument = { name: 'John Doe', preferred_email: 'johndoe111@test123.test' };
result = await sampleColl.upsert(user, collDocument);

Additional Resources

Working on just a specific path within a JSON document will reduce network bandwidth requirements - see the Sub-Document pages.

Another way of increasing network performance is to pipeline operations with Batching Operations.

As well as various Formats of JSON, Couchbase can work directly with arbitary bytes, or binary format.

Our Query Engine enables retrieval of information using SQL++ (formerly N1QL).