Design Couchbase Document Keys to Avoid Hotspots (2026)

Couchbase document keys aren’t just identifiers; they’re the primary mechanism for distributing data and load across your cluster, and getting them wrong is the fastest way to create performance bottlenecks.

Let’s see how this plays out in a real scenario. Imagine we have a simple e-commerce application tracking orders. A naive approach might generate keys like order_12345, order_12346, and so on.

// Example document with a naive key
{
  "id": "order_12345",
  "customer_id": "cust_abc",
  "items": [...],
  "status": "processing"
}

If we have a high volume of new orders being created, all these keys will likely fall into a predictable pattern. Couchbase’s hashing algorithm, which determines which vBucket (and therefore which node) a document resides on, will map these sequential keys to a very small subset of vBuckets. If those vBuckets happen to be on the same node, or a small group of nodes, that node(s) will receive a disproportionate amount of write traffic. This is a "hotspot."

The core problem is that the hashing algorithm on sequential or predictable keys leads to uneven distribution. Couchbase’s internal hashing function takes the document key and produces a number, which is then mapped to a vBucket. If your keys are 1, 2, 3, 4..., they’ll likely hash to a tight range of numbers, and thus a tight range of vBuckets.

The Solution: Randomization

The key to avoiding hotspots is to introduce randomness or a high degree of entropy into your document keys. This ensures that the hash function distributes keys evenly across all available vBuckets, and consequently, across all nodes in your cluster.

1. UUIDs (Universally Unique Identifiers): The simplest and most robust solution is to use UUIDs. These are 128-bit numbers guaranteed to be unique across space and time.

• Diagnosis: Observe your cluster’s active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active active