FAQ - Understanding time to live on an Aerospike cluster

The Aerospike Knowledge Base has moved to https://support.aerospike.com. Content on https://discuss.aerospike.com is being migrated to either https://support.aerospike.com or https://docs.aerospike.com. Maintenance on articles stored in this repository ceased on December 31st 2022 and this article may be stale. If you have any questions, please do not hesitate to raise a case via https://support.aerospike.com.

How do I use configurations default-ttl, max-ttl and cold-start-evict-ttl?

  • By default, Aerospike does not set any time-to-live on the records that it writes on the server unless default-ttl is set on the namespace and relies on the application to maintain or clean-up data as necessary. In the event that you rely on Aerospike’s expirations to maintain the capacity limits on the server, you can set the default-ttl accordingly. Note that this is set at the namespace level and is a dynamic configuration (does not require an Aerospike service restart).
  • max-ttl defines the upper limit to the TTL that can be set on the records. This configuration is used to prevent the server from getting data from rogue clients with TTL higher than expected. This has an upper limit of 10 years (even if this configuration is not set explicitly).
  • default-ttl cannot be set higher than the max-ttl .
  • cold-start-evict-ttl is used to define the TTL such that records having TTL below this value will be evicted during a cold-start of Aerospike service. This helps speed up cold-start process in case of evictions during cold restart.

What is the maximum limit of these configurations that can be set on a namespace?

  • default-ttl cannot be set higher than max-ttl .
  • max-ttl cannot be set higher than 10 years (for versions 3.8.3 and above).
  • cold-start-evict-ttl does not have an upper limit as such, but knowing that the max-ttl on the server cannot be beyond 10 years, this limit holds true for the cold-start-evict-ttl as well.

How to change TTL from server and application?

What are the range for the TTL? Why is there -1 and -2?

The TTL are basically positive integers with the value 0 (on the server) referring to non-expirable data.

  • From the client API:
    • When setting TTL to -1 in the client policy, data will never expire. Internally, the record is stored as 0.
    • When setting TTL to 0 in the client policy, the record TTL will use the value specified by default-ttl.
    • When setting TTL to -2 in the client policy, the record TTL will not be updated when the record is updated but will use the default-ttl value at record creation. Available for server version 3.10.1 and above.

For details, refer to the Setting TTL for Data Expiration document.

How to determine non-expirable records?

You can use the following asadm command to determine the number of non-expirable records for 3.9+:

show stat like non_expirable_objects

Metrics Reference | Aerospike Documentation 16


show stat like non-expirable-objects

To find all those records, a backup (asbackup) and grep for the pattern “^+ t 0” in the backup files. Refer to the Backup File Format for relevant details.

Alternatively, one can write a UDF to scan records based on the record.ttl field. It could turn into an intensive operation that may affect a production system’s performance.

The How to Modify TTL using UDF article provides such example.

TTL related WARNINGs

For versions 3.8.3 and above:

  1. If the max-ttl is configured lower than the default-ttl:
WARNING (info): (thr_info.c:2934) max-ttl must be >= default-ttl (current value in seconds)
  1. If the incoming TTL record is configured more than the configured max-ttl:
WARNING (rw): (write.c:776) write_master: invalid ttl 'value of incoming TTL'
  1. If the max-ttl is configured to higher than the global maximum of 10 years:
WARNING (info): (thr_info.c:2930) max-ttl must be non-zero and <= 315360000 seconds

For versions prior to 3.8.3:

The following warnings are seen which point towards an anomaly in the TTL values.

Note that in versions prior to 3.8.3, we did not have an explict check on the default-ttl and max-ttl values. And the default value of max-ttl was 0.

  1. If the incoming TTL is configured more than the max-ttl (e.g. max-ttl = 8640000 = 100 days), you would see one of these warnings:
WARNING (rw): (thr_rw.c:3226) write_local: incoming ttl 4294938278 too big compared to 8640000
WARNING (rw): (thr_rw.c::3197) record TTL 1459720873 exceeds warning threshold 315360000 - set config value max-ttl to suppress this warning