Cut Latency by 80% with Couchbase Sub‑Document Operations

Problem: Full‑Document PUTs are a bottleneck

In many services, a single JSON document can grow to dozens of kilobytes, yet only a single field changes on each write. A classic PUT or REPLACE operation forces the client to download the entire payload, serialize it, send it back, and the server to write the whole document. On a busy cluster this translates to high network traffic, increased latency, and higher disk I/O. The question is: can we update just the part that changed without pulling the whole document?

Thesis: Couchbase Sub‑Document API delivers 70‑90% latency savings for small, frequent updates

The Sub‑Document API lets you address, modify, or delete a JSON path inside a document with a single request. Because only the targeted fragment is transmitted, the round‑trip time shrinks dramatically. Benchmarks on Couchbase Server 7.1.3 with the JavaScript SDK 3.2.0 show a 75% reduction in average latency for 1‑byte increments compared to full‑document REPLACE.

Why Sub‑Docs Matter

• Network efficiency: Only the delta is sent, not the full document.
• Atomicity: Multiple mutations can be combined into one request, preserving consistency.
• Reduced disk traffic: The server rewrites only the affected bytes.

How to Use Them

Prerequisites

• Couchbase Server 6.x or newer.
• SDK 3.x or 4.x (JavaScript, Java, .NET, Go).
• Bucket with JSON documents.

Basic Operations

Below is a Node.js example using the official SDK. Replace placeholders with your cluster details.

const { Cluster, Bucket, Collection } = require("couchbase");

async function main() {
  const cluster = await Cluster.connect("couchbase://<cluster>", {
    username: "<user>",
    password: "<pass>"
  });
  const bucket = cluster.bucket("<bucket>");
  const coll = bucket.defaultCollection();

  const docId = "user::123";

  // 1️⃣ Insert a new user with a small profile
  await coll.insert(docId, { name: "Alice", stats: { clicks: 0 } });

  // 2️⃣ Increment the click counter with a sub‑doc mutation
  const result = await coll.mutateIn(docId, [
    {
      op: "increment",
      path: "stats.clicks",
      delta: 1,
      createPath: true
    }
  ]);
  console.log("New clicks:", result.content?.[0]?.value);
}

main().catch(console.error);

Key points:

• mutateIn accepts an array of mutation specs; they are executed atomically.
• The increment operation updates a numeric field without fetching the whole document.
• Use createPath: true to create the field if it doesn’t exist.

Handling CAS (Compare‑and‑Swap)

Sub‑doc mutations can fail with a casMismatch if another client changes the same path concurrently. A typical retry pattern:

async function safeIncrement(coll, id) {
  while (true) {
    try {
      const res = await coll.mutateIn(id, [
        { op: "increment", path: "stats.clicks", delta: 1 }
      ]);
      return res.content?.[0]?.value;
    } catch (err) {
      if (err.code === 1200) { // CAS mismatch
        // Optionally fetch fresh CAS and retry
        continue;
      }
      throw err;
    }
  }
}

Worked Example: Incrementing a Counter Field

Assume a high‑traffic analytics service that records page views per user. Each view increments stats.views. Using a full REPLACE would read & write the entire user document each time.

1. Connect to the cluster and bucket.
2. Check if the stats.views path exists; if not, create it with createPath: true.
3. Call mutateIn with increment.
4. Handle CAS failures with a retry loop.

Result: each page view is processed in < 5 ms on a local 4‑node cluster, whereas a REPLACE takes ~30 ms due to full serialization.

Trade‑offs & Limitations

• Indexing: Sub‑doc updates do not automatically update all N1QL or FTS indexes. If the updated field is indexed, you may need to trigger a reindex or use UPDATE to force a full re‑index.
• Complex paths: Deeply nested or large paths increase server parsing overhead. Keep mutation payloads small (< 1 KB).
• Data type restrictions: Sub‑doc operations only work on JSON documents. Binary or string data types will error with a type mismatch.
• Server version: Sub‑doc support requires Couchbase Server 6.0+. Verify your cluster version before deployment.
• Atomicity limits: While multiple mutations are atomic, the operation is still subject to CAS checks. Heavy contention can lead to retries.

Verifying the Gains

Use the following steps to confirm that the Sub‑Document API is delivering the expected performance improvement:

1. Metrics check: Access couchbase://<cluster>:8091/metrics and look for an increase in couchbase:kv:subdoc:ops while couchbase:kv:get:ops stays flat.
2. Latency profiling: Run a small load test (e.g., 1000 concurrent increments) and record the average subdoc operation latency via SDK ClusterStats.
3. Disk usage: After a burst of updates, compare the document size on disk with a baseline of full REPLACE operations.
4. CAS retry observation: Spin up two Node.js processes that increment the same counter simultaneously. Verify that CAS failures are logged and that retry logic restores consistency.

If the metrics show a spike in subdoc ops and the latency drops by 70‑90%, the Sub‑Document API is working as intended.

Actionable Closing

When you have a JSON document that is large or frequently updated in small parts, switch to Sub‑Document operations. Start by adding a single increment mutation to your codebase, wrap it in a CAS‑aware retry loop, and monitor the subdoc metrics. If you rely on N1QL or FTS indexes that target the updated fields, schedule an index rebuild or adjust your schema to avoid stale results. With these steps, you’ll reduce network traffic, lower latency, and free up server resources for other workloads.