Couchbase Memory Quota Calculator
Couchbase doesn't have one memory limit: each service (Data, Index, Search, Eventing, Analytics) has its own quota per node, and every bucket gets a quota carved out of the Data service's. This calculator sizes each bucket from its document count, size, replicas and how much of it should stay in RAM, then works out the Data quota per node and checks that all the quotas fit in the node's memory.
01 Buckets
Where do I get these?
Each paste fills in what it contains, so paste more than one in turn. Buckets and document counts, from the bucket API (also gives replicas, eviction policy and the current quota):
curl -s -u Administrator:"$CB_PASSWORD" http://localhost:8091/pools/default/buckets
Nodes, node RAM and the service quotas, from the cluster API:
curl -s -u Administrator:"$CB_PASSWORD" http://localhost:8091/pools/default
Or document counts as Prometheus metrics, from every Data node's /metrics endpoint — each node counts only its own active items, so paste them all and they're added up — or from a Prometheus kv_curr_items query, as text or API JSON:
curl -s -u Administrator:"$CB_PASSWORD" http://localhost:8091/metrics | grep -E '^kv_(curr_items|ep_cache_size)'
Document and key sizes aren't in any of them; average a sample of your documents.
One block per bucket. Document and key sizes are averages; get them from a sample of real documents.
02 Cluster layout
03 Other services
Quota per node, in MiB, for each service running on those nodes. These aren't calculated: each is added as entered to the node's total. Leave 0 for a service that isn't deployed; one that runs needs at least 256 MiB (Analytics 1024 MiB).
Advanced: sizing defaults and thresholds
Values the result relies on that are Couchbase’s sizing defaults, or our own thresholds for the warnings. Each “?” says how one moves the result; the guide says where it comes from.
04 couchbase-cli
—05 How this was derived
How every number is calculated, with sources and assumptions (opens in a new tab) ↗
Result looks wrong? Report it
Service and bucket quotas in short
Couchbase doesn't have one memory limit. It has two levels of quota, nested inside the node's RAM: a quota per service on each node (Data, Index, Search, Eventing, Analytics; Query has none and uses whatever the operating system has left), and a quota per bucket, taken out of the Data service's. All bucket quotas together must fit in the Data quota. Couchbase docs
This calculator doesn't use the average-and-peak model of the other pages. It applies Couchbase's own Data service sizing formula to each bucket from its document count, size, replicas and working set, spreads the result over the Data nodes, and checks that all the quotas fit in the node's RAM. The overhead, metadata size and high-water mark can be changed under Advanced. Couchbase docs
The formula is written for the Couchstore storage engine, so the calculator assumes buckets use it; Magma buckets can run with much less memory.
Common input mistakes
- Guessing document and key sizes: nothing in the metrics or REST APIs gives them reliably, so average a sample of real documents.
- Leaving out replicas: every replica is a full extra copy of the bucket's data and metadata, held in the same quota.
- Forgetting the other services: Index, Search, Eventing and Analytics quotas are added as entered to the node's total.
Full derivation, warnings and every assumption: how the Couchbase calculator works.
Related calculators: