Changing ejection thresholds

Changing ejection thresholds

The item pager process ejects items from RAM when too much space is being taken up in RAM.


Ejection means that documents are removed from RAM but the key and metadata remain. If the amount of RAM used by items reaches the high water mark (upper threshold), both active and replica data are ejected until the memory usage (amount of RAM consumed) reaches the low water mark (lower threshold). The server determines that items are not frequently used based on a not-recently-used (NRU) value.

Use the mem_low_wat , mem_high_wat , and pager_active_vb_pcnt settings to change the server thresholds for ejection.

Warning: We do not recommend that you change the ejection defaults unless required by Couchbase Support.
Note: Changes of thresholds are NOT persistent and must be reapplied after the bucket warmup.


Basic syntax:

cbepctl [localhost]:11210 -b [bucket-name] -p [bucket-password] set flush_param [parameter] [value]

Parameters used for changing ejection thresholds:

  • mem_low_wat
  • mem_high_wat
  • pager_active_vb_pcnt

Example: Setting the low water mark

The low water mark sets the lower threshold of RAM for a specific data bucket on a node. The item pager stops ejecting items once the low water mark is reached.

The following example sets the low water mark percentage to 70% of RAM.

cbepctl -b foo-bucket -p foo-password set flush_param mem_low_wat 70

Example: Setting the high water mark

The high water mark set the amount of RAM consumed by items that must be breached before infrequently used active and replica items are ejected.

The following example sets the high water mark percentage to 80% of RAM for a specific data bucket on a node. This means that items in RAM on this node can consume up to 80% of RAM before the item pager begins ejecting items.

cbepctl -b foo-bucket -p foo-password set flush_param mem_high_wat 80

Example: Setting percentage of ejected items

Based on the NRU algorithm, the server ejects active and replica data from a node. By default, the server is configured to 40% active items and 60% replica data from a node.

The following example increases the percentage of active items that can be ejected from a node to 50%.

cbepctl -b foo-bucket -p foo-password set flush_param pager_active_vb_pcnt 50

Be aware of potential performance implications when changing the percentage of ejected items. It may be more desirable to eject as many replica items as possible and limit the amount of active data that can be ejected. By doing so, active data from a source node is maximized while maintaining incoming requests to that node. However, if the server is ejecting a very large percentage of replica data and a node fails, the replica data is not immediately available. In this case, the items are retrieved from disk and put back into RAM before the request is fulfilled.


The following example response shows the low water mark, high water mark, and percentage of ejected items being set.

setting param: mem_low_wat 70
set mem_low_wat to 70

setting param: mem_high_wat 80
set mem_high_wat to 80

setting param: pager_active_vb_pcnt 50
set pager_active_vb_pcnt to 50