Using Couchbase Sub‑Document API for Atomic Partial Updates

The problem: costly full‑document writes

Many applications need to change a single field—such as a user’s email address—frequently. With a traditional replace operation the client must read the whole JSON document, modify the field locally, and send the entire document back to Couchbase. This approach wastes bandwidth, adds latency, and creates a read‑modify‑write race: if another process updates the same document between the read and the write, the second change is lost unless the application implements its own locking or retry logic.

Why Sub‑Document helps

Couchbase Server 5.0+ exposes a Sub‑Document API that lets the client send only the mutation (e.g., replace the value at "email") and the server applies it atomically. The operation uses the document’s CAS (Compare‑And‑Swap) value to guarantee that concurrent updates either succeed or fail with a clear CAS_MISMATCH error, eliminating the need for a separate fetch.

Worked example with the Java SDK 3.x

Assume you have a bucket travel-sample, scope inventory, and collection user. The user document key is the user ID, e.g., user::123.

// Required imports
import com.couchbase.client.core.error.CasMismatchException;
import com.couchbase.client.java.Collection;
import com.couchbase.client.java.kv.MutateInSpec;
import com.couchbase.client.java.kv.MutateInResult;

// 1. Obtain a collection instance (needs read/write permissions on the bucket)
Collection userCol = cluster.bucket("travel-sample").scope("inventory").collection("user");

// 2. Perform a sub‑document replace of the email field
String userId = "user::123";
String newEmail = "[contact removed]";
try {
    MutateInResult result = userCol.mutateIn(userId,
            MutateInSpec.replace("email", newEmail))
            .execute();
    // The result contains the new CAS; you can log it or use it for further ops
    System.out.println("Update succeeded, new CAS: " + result.cas());
} catch (CasMismatchException e) {
    // CAS changed since the last read – another client won the race
    System.err.println("Conflict detected, retry logic should be applied");
    // Example retry: re‑read the document and attempt the mutateIn again
} catch (Exception e) {
    // Other errors (e.g., PathInvalidError) – handle as appropriate
    e.printStackTrace();
}

Where to run: any Java environment with the Couchbase Java SDK 3.x on the classpath. Required permissions: the SDK user must have bucket.read and bucket.write on the target bucket. Expected checks: after a successful call, the returned MutateInResult includes a non‑null CAS; on conflict you receive a CasMismatchException. Risks: if the path "email" does not exist, the server returns a PathInvalidError (subclass of CouchbaseException) and the mutation is ignored—make sure to catch and log such errors.

Trade‑offs and limitations

• Network efficiency: a Sub‑Document request is often under 100 bytes, versus several kilobytes for a full replace.
• Built‑in concurrency control: CAS‑based conflict detection removes the need for application‑level locks.
• Operation scope: only primitive mutations (replace, upsert, array append, prepend, insert, etc.) on known paths are supported. Complex transformations that depend on other fields or require server‑side logic still need a full‑document fetch or an N1QL UPDATE.
• Version requirement: the feature requires Couchbase Server 5.0+ and a compatible SDK; older clusters will throw an UnsupportedOperationException.

Practical verification steps

1. Start a local Couchbase Server 7.2 instance via Docker (requires Docker daemon access):

   docker run -d -p 8091-8096:8091-8096 -p 11210:11210 couchbase/server:7.2.0

2. Create a bucket, scope, and collection (via the UI or CLI) and insert a test document:

cbdocloader -u Administrator -p password -n travel-sample -b travel-sample -s 100 -u http://localhost:8091

3. Run the Java mutateIn snippet above, capture the request size with Wireshark or enable the SDK’s request‑tracing (-Dcom.couchbase.tracing.enabled=true). Compare the size to a full replace operation; you should see a markedly smaller payload.
4. Launch a second thread that calls mutateIn on the same key with a different field (e.g., updating "phone"). Verify that the second call throws a CasMismatchException, confirming atomic conflict detection.

Actionable closing

Adopt the Sub‑Document API for high‑frequency partial updates where the change can be expressed as a primitive field mutation. Monitor latency and error rates via the SDK’s diagnostics, and fall back to a full‑document replace only when the update logic cannot be expressed as a primitive mutation. This approach gives you network savings and built‑in concurrency control while keeping the code straightforward.