Documents

Couchbase supports CRUD operations, various data structures, and binary documents.

Although query and path-based (Sub-Document) services are available, the simplicity of the document-based key-value (kv) interface is the fastest way to perform operations involving single documents.

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

Primitive Key-Value Operations

upsert(String docid, Object document)
insert(String docid, Object document)
replace(String docid, Object document)
get(String docid)
remove(String docid)

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

If you wish to only modify certain parts of a document, you can use sub-document operations which operate on specific subsets of documents:

List<MutateInSpec> spec = Collections.singletonList(
        MutateInSpec.upsert("msrp", 18.00)
);
collection.mutateIn("airline_10", spec);

or N1QL UPDATE to update documents based on specific query criteria:

update `travel-sample`.inventory.airline SET sale_price = msrp * 0.75 WHERE msrp < 19.95;

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

SELECT * FROM `travel-sample`.inventory.airport USE KEYS ["airport_1254"];

SELECT * FROM `travel-sample`.inventory.airport WHERE META().id = "airport_1254";

You can also retrieve parts of documents using sub-document operations, by specifying one or more sections of the document to be retrieved

Collection usersCollection = bucket.scope("tenant_agent_00").collection("users");
List<LookupInSpec> spec = Arrays.asList(
        LookupInSpec.get("credit_cards[0].type"),
        LookupInSpec.get("credit_cards[0].expiration")
);
usersCollection.lookupIn("1", spec);

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

String counterDocId = "counter-doc";
// Increment by 1, creating doc if needed.
// By using `.incrementOptions().initial(1)` we set the starting count(non-negative) to 1 if the document needs to be created.
// If it already exists, the count will increase by 1.
collection.binary().increment(counterDocId, IncrementOptions.incrementOptions().initial(1));
// Decrement by 1
collection.binary().decrement(counterDocId);
// Decrement by 5
collection.binary().decrement(counterDocId, DecrementOptions.decrementOptions().delta(5));

You can simplify by importing decrementOptions() statically:

collection.binary().decrement(counterDocId, decrementOptions().delta(5));

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

GetResult getResult = collection.get("counter-doc");
int value = getResult.contentAs(Integer.class);
int incrementAmnt = 5;

if (shouldIncrementAmnt(value)) {
    collection.replace(
            "counter-doc",
            value + incrementAmnt,
            ReplaceOptions.replaceOptions().cas(getResult.cas())
    );
}

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]

Use Cases

The SDK provides a high-level abstraction over the simple incr()/decr() of Couchbase Server’s memcached binary protocol, using collections.binary(). This enables you to work with counters using get() and upsert() operations — allowing, inter alia, the use of durability options with the operations. You will find several ways of working with counters in the API docs.

Unresolved include directive in modules/concept-docs/pages/documents.adoc - include::7.1.2@sdk:shared:partial$documents.adoc[]