Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Memory

      +
      Couchbase Server memory-management ensures high performance and scalability.

      Service Memory Quotas

      You must configure your memory quota allocations for each service in Couchbase Server, except for the Query Service and Backup Service. You can change the availability of memory resources in your cluster based on how you assign your services to each node.

      The memory quota you allocate for a service applies to every instance of that service across your cluster. For example, if you allocate 2048 MB to the Analytics Service, and you run the Analytics Service on three of a cluster’s five nodes, each instance of the service has 2048 MB of memory.

      You can’t allocate different amounts of memory for different instances of the same service in a cluster.

      Couchbase recommends that you allocate no more than 90% of a node’s memory (80% on nodes with a small amount of total memory) to a server and its services.

      The firm limits for server memory allocation can be calculated by:

      \(max(total\_memory - 1, 80\% \times total\_memory)\)

      where total_memory is the maximum memory on the node in GiB.

      The Data Service must run on at least one node in any cluster. Every bucket you create on a node has its own memory quota. The available memory for a bucket comes from the quota you assign to the Data Service. For more information on bucket memory quotas, see the Bucket Memory Quotas section.

      When you add a new node, you can use the same configuration and services from the first node in the cluster. You can also choose to customize the new node’s settings and change its assigned services.

      For more information about how to add nodes and allocate memory to a service when you initialize a cluster, see Create a Cluster.

      The Memory Quotas panel in the General settings screen of the Couchbase Server Web Console lists all the services running on a cluster. It also shows the memory allocated to each service. You can use the panel to change the memory allocations in your cluster. If a change doesn’t meet the required minimum or exceeds the available memory for a cluster, the Memory Quotas panel displays an error.

      The following table contains the minimum required memory quotas for each service in Couchbase Server:

      Service Minimum Memory Quota (in MB)

      Data

      256

      Index

      256

      Search

      256

      Analytics

      1024

      Eventing

      256

      The Query Service and the Backup Service don’t require an administrator-specified memory quota.

      Bucket Memory Quotas

      You must specify a memory quota for each bucket you create. This quota is allocated for the bucket on a per node basis and must be less than the total memory quota for the cluster.

      Set the memory quota based on the expected size of your dataset. The memory quota for a bucket must support the minimum memory resident ratio of its storage engine:

      • Couchstore: The memory quota is recommended to be at least 10-20% of your expected dataset size.

      • Magma: The memory quota is recommended to be at least 2% of your expected dataset size.

      For example, if you expect to have about 2TBs of data per node in your cluster and want to use the Magma engine, you could set the memory quota for a bucket to 40GB.

      These values are recommendations only. The specific memory quota requirements for your bucket are dependent on access patterns, data density, and other factors.

      For more information on how to create a bucket and configure its memory quota, see Create a Bucket.

      Initialization and Warmup

      When Couchbase Server is restarted on a node, the node goes through a warmup process before it restarts the handling of data requests. During this warmup process, data on disk is sequentially reloaded into memory for each bucket. The time required for the reload depends on the size and configuration of the system, the amount of data persisted on the node, and the ejection policy configured for the buckets.

      On a given Data Service node, a bucket’s data is loaded in accordance with determinations made by the access scanner. This program runs by default once every day. It checks the resident ratio — which is the percentage of items in active and replica vBuckets that are currently in memory on the node:

      • If the ratio is below 95%, the access scanner generates a new access log, which records the documents that have been most frequently accessed during the last 24 hours. If and when data-loading subsequently occurs, the new access log is consulted, the recorded document-keys obtained, and the corresponding documents loaded with the highest priority.

      • If the ratio is above 95%, the access scanner does not generate a new access log. Instead, it deletes any existing access log, and exits. If and when data-loading subsequently occurs, since no access log exists, loading occurs with no priority-order (this being, in cases of extremely high resident ratio, the more performative loading procedure).

      Configuring the Access Scanner

      The access scanner is configurable, via the CLI utility cbepctl, with the flush_param parameter. This utility also provides the parameters warmup_min_memory_threshold and warmup_min_item_threshold, which can be used to schedule the resumption of traffic before all items have been reloaded into memory.

      Note that the access scanner is a highly CPU-intensive process, whose configurable start-time should ideally be established as different for each Data Service node in the cluster. See set flush_param.

      Ejection

      If a bucket’s memory quota is exceeded, items may be ejected from the bucket by the Data Service.

      Different ejection methods are available, and are configured per bucket. Note that in some cases, ejection is configured not to occur.

      For a Couchbase bucket, you can choose betweeen a Value-only or Full ejection method:

      • Value-only: The bucket only ejects data when it removes a document from memory. Choose this method if you need better performance, but be aware that it uses more system memory.

      • Full: The bucket ejects data, metadata, keys, and values when it removes a document from memory. Choose this method if you want to reduce your memory overhead requirement.

      For an Ephemeral bucket, you can choose between a No ejection or Eject data when RAM is full ejection policy:

      • No ejection: If the bucket reaches its memory quota, the bucket doesn’t eject any existing data and attempts to cache new data fail.

      • Eject data when RAM is full: If the bucket reaches its memory quota, the bucket ejects older documents from RAM to make space for new data.

      Ejection from Ephemeral buckets removes data without persistence because Ephemeral buckets have no presence on disk.

      For more information about buckets and bucket types, see Buckets.

      For each bucket, available memory is managed according to two watermarks, which are mem_low_wat and mem_high_wat. If data is continuously loaded into the bucket, its quantity eventually increases to the value indicated by the mem_low_wat watermark. At this point, no action is taken. Then, as still more data is loaded, the data’s quantity increases to the value indicated by the mem_high_wat watermark. If, based on the bucket’s configuration, items can be ejected from the bucket, the Data Service ejects items from the bucket until the quantity of data has decreased to the mem_low_wat watermark. In cases where ejection cannot free enough space to support continued data-ingestion, the Data Service stops ingesting data, error messages are sent to clients, and the system displays an insufficient memory notification. When sufficient memory is again available, data-ingestion resumes.

      Items are selected for ejection based on metadata that each contains, indicating whether the item can be classified as Not Recently Used (NRU). If an item has not been recently used, it is a candidate for ejection.

      The relationship of mem_low_wat and mem_high_wat to the bucket’s overall memory quota is illustrated as follows:

      tunableMemory

      The default setting for mem_low_wat is 75%. The default setting for mem_high_wat is 85%. The default settings can be changed by means of the cbepctl utility. See set flush_param.

      Expiry Pager

      Scans for items that have expired, and erases them from memory and disk; after which, a tombstone remains for a default period of 3 days. The expiry pager runs every 10 minutes by default: for information on changing the interval, see cbepctl set flush_param. For more information on item-deletion and tombstones, see Expiration.

      Active Memory Defragmenter

      Over time, Couchbase Server-memory can become fragmented. Each page in memory is typically responsible for holding documents of a specific size-range. Over time, if memory pages assigned to a specific size-range become sparsely populated (due to documents of that size being ejected, or to items changing in size), the unused space in those pages cannot be used for documents of other sizes, until a complete page is free, and that page is re-assigned to a new size. Such effects, which are highly workload-dependent, may result in memory that cannot be used efficiently.

      Couchbase Server provides an Active Memory Defragmenter, which periodically scans the cache, to identify pages that are sparsely used. It then repacks the items on those pages, to free up space.