Skip to main content

Namespace Retention Configuration

To ensure sufficient memory for your operation and to allow the cluster to process new writes, Aerospike namespaces can be configured to expire or evict records based on criteria you define.

Definition of eviction and expiration

To determine a record's eligibility for removal, the expiration algorithms use a record's TTL (Time To Live).

Independently from expiration, if storage in use exceeds a configurable high-water mark, to reclaim memory, the eviction process deletes as-yet unexpired records that are about to expire (those records nearest their expiration times). Eviction continues until sufficient space has been recovered. Eviction can be thought of as "early expiration".

By default, expiration and eviction are disabled. You must configure them with certain configuration parameters.

Configuration parameters

These parameters are configurable per namespace. For the exact definition and use of a parameter, see the configuration reference or click the name of a parameter below.

Other related parameters are shown in Examples of configuration stanzas.

Configuration parameterDescriptionDefault valueNotes
nsup-periodFrequency in seconds of expiration and eviction process.0By default, expiration and eviction do not happen.

When nsup-period is 0, to allow writes that have a non-zero TTL , you must set allow-ttl-without-nsup to true. See allow-ttl-without-nsup below.

Regardless of the setting of nsup-period, writes with a TTL of 0 are always allowed.
high-water-disk-pctThreshold for disk at which eviction process starts.0
high-water-memory-pctThreshold for memory at which eviction process starts.0
mounts-high-water-pctThreshold at which eviction process starts when configured for index in flash or pmem.0
default-ttlRecords' default time to live in seconds.0If the value of default-ttl is non-zero and nsup-period is zero (the default), the Aerospike server will not start.

Aerospike never expires or evicts records that have been stored with a TTL of 0.

When client applications create records, they can override this value.
allow-ttl-without-nsupAllows writes of records with non-zero TTL even if nsup-period is 0. Not recommended to change other than special use cases where the application will handle expirations. See also the caution in Be careful with records that have a TTL when nsup is not running.falseWhen nsup-period is 0, if you want to write records that have a non-zero TTL, allow-ttl-without-nsup must be set true.
stop-writes-pctLimit of memory in use to disallow further writes.90Deletions, replication writes, and migration writes are still allowed.
min-avail-pctLimit of free storage contiguous space to disallow further writes.5Deletions, replication writes, and migration writes are still allowed.

Choosing appropriate parameter values

Be aware of the ramifications of values you set for these parameters.

High-water marks

As an example, setting high-water-disk-pct to 20 means that you are ensuring that your storage device will be no more than 20% full, which is probably not desirable.

Be careful changing default Time-To-Live

Depending on your use case it might be desirable to not set default-ttl (leaving it at default 0) and manage the data from your client application, which can set TTL per record.

Be careful with records that have a TTL when nsup is not running

Be aware of the treatment of records with TTLs when nsup is not running (that is, when nsup-period is 0, which is the default). Requests to read a record will honor the TTL, return AEROSPIKE_ERR_RECORD_NOT_FOUND and delete the record when the record has passed its expiration time. But if nsup is not running, expired records are never removed from the index or physically removed from storage (unless they are explicitely accessed through a transaction). Note that records written with a non 0 TTL will not be allowed by default when nsup-period is set to 0 and will be rejected with the AEROSPIKE_ERR_FAIL_FORBIDDEN error.


With the client API, reducing a record's TTL less than its current remaining life may have undesirable side effects upon a cold restart. For further details, see Issues with cold-start resurrecting deleted records.

Examples of configuration stanzas

The following example shows the applicable namespace data retention parameters and a short comment describing how they are used.

namespace namespaceName {
default-ttl <VALUE> # How long (in seconds) to keep data after
# it is written (if not overwritten by Client)

high-water-disk-pct <PERCENT> # How full may the disk become before the
# server begins eviction

high-water-memory-pct <PERCENT> # How full may the memory become before the
# server begins eviction

stop-writes-pct <PERCENT> # How full may the memory become before
# we disallow new writes

index-type flash/pmem { # If applicable
mounts-high-water-pct <PERCENT> # How full flash index storage may become
# before server begins eviction


Tuning parameters

The following example shows additional namespace data retention parameters to tune data expiration and eviction, with comments describing usage.

namespace <namespace-name> {
nsup-period <SECONDS> # As of Aerospike 4.5.1 (at service level prior)
# Maximum time between starting successive
# rounds of expiration or eviction - a value
# of zero disables expiration and eviction

nsup-threads <NUMBER> # As of Aerospike 4.5.1
# How many threads per round of expiration
# or eviction

evict-tenths-pct <NUMBER> # Fraction of evictable records to delete
# per round of eviction. For example, 5 means
# delete 0.5 percent of evictable records)


Set Disable Eviction

A set can be protected from evictions with parameter disable-eviction true, as shown in the following example. This parameter can be set in the configuration file and dynamically.

namespace <namespace-name> {
set <set-name> {
disable-eviction true # Protect this set from evictions


prior to Aerospike 5.6 this configuration parameter was called set-disable-eviction.

Set Stop Writes Count

A set can have stop-writes-count to limit the number of records that can be written to it. This parameter can be set in the configuration file and dynamically.

namespace <namespace-name> {
set <set-name> {
stop-writes-count 5000 # Limit the number of records that can
# be written to this set to 5000.


prior to Aerospike Database 5.6 this configuration parameter was called set-stop-writes-count.

Set Index

As of Aerospike 5.6, a set index can be enabled or disabled dynamically

In the configuration file a set index is defined as follows:

namespace <namespace-name> {
set <set-name> {
enable-index true

Historical behavior by Aerospike Version

Aerospike Version 4.9

The settings and behavior of data retention is as described above. Expirations and evictions are disabled by default.

Aerospike Version 4.5.1

As of Aerospike Server 4.5.1, expirations and evictions are accomplished by deleting records locally on each node, without generating any transaction load. This enables use cases with heavy expiration or eviction loads which were not possible before.

This new methodology has a somewhat stronger dependence on clocks being synchronized across nodes in a cluster. As of Aerospike Server 4.5.1, for each namespace where nsup is enabled (i.e. nsup-period not zero) writes will be suspended if cluster clock skew exceeds 40 seconds.

Also, as of Aerospike Server 4.5.1, if eviction thresholds are not configured the same on all nodes in the cluster, the node with the lowest threshold will drive eviction across the cluster. When a node breaches its eviction threshold, it broadcasts a cutoff void-time to the rest of the cluster. Prior to 4.5.1, a node with a lower threshold would evict heavily from the partitions for which it is master.

Aerospike Version 3.8.1

When evictions are in effect, Aerospike groups records by buckets based on their expiration time and evicts randomly within each bucket, emptying a bucket before moving to the next one. In Aerospike Server 3.8.1 and up, a more granular eviction histogram has been introduced along with a configuration parameter: evict-hist-buckets. In Aerospike Server or earlier there are always 100 buckets. The bucket boundaries are determined based on the record with the longest expiration time in the namespace. The longer the expiration time of this record, the less precise the eviction will be since the buckets will have broader ranges.

Prior to Aerospike Server 4.5.1, expirations and evictions are accomplished by internally generating delete transactions, including replica deletion via the fabric. For heavy expiration and eviction loads, these transactions can noticeably impact overall performance.

See FAQ What are Expiration, Eviction and Stop-Writes?

Where to Next?