Skip to main content

TTL and expiration

A time-to-live (TTL) is a duration you attach to a key that tells Clustron Zaris how long the key should exist. When the TTL elapses, the key is removed automatically, so you get time-based cleanup without writing any cleanup code.

What TTL means​

TTL defines the lifetime of a key. You set it as a duration when you write the key, and once that duration passes the key expires: it is removed and its value is no longer accessible. Nothing in your application has to run to make this happen — expiration is the system's job.

Setting a TTL​

You attach a TTL when you store a value by passing put options built with Put.WithTtl:

await client.PutAsync(
    "session:abc123",
    "active",
    Put.WithTtl(TimeSpan.FromMinutes(10)));

This key exists for 10 minutes from the write, then expires on its own.

Reading a key that can expire​

A get on an expiring key looks like any other read. What changes is the result once the key is gone:

var result = await client.GetAsync<string>("session:abc123");

if (result.IsSuccess)
{
    Console.WriteLine(result.Value);
}

Before the TTL elapses, IsSuccess is true and Value holds your data. After it elapses, IsSuccess is false, Status is KvStatus.NotFound, and the key behaves exactly as if it never existed. Always check IsSuccess rather than assuming the key is present, because an expiry can happen between one read and the next.

Extending a TTL​

To reset a key's TTL in place — without rewriting its value — call ExpireAsync with a fresh duration:

await client.ExpireAsync("session:abc123", TimeSpan.FromMinutes(10));

This gives the key a new 10-minute lifetime from the moment of the call, effectively extending it. Re-putting the key with Put.WithTtl also resets its TTL, so you can extend either way; ExpireAsync is the lighter option when the value has not changed. Applications keep short-lived data alive this way — for example, refreshing a session's TTL each time the user acts.

Two companion calls round out TTL management: PersistAsync removes a key's TTL and makes it permanent, and GetTimeToLiveAsync returns the remaining time-to-live (or null when the key has no TTL, and KvStatus.NotFound when the key is absent).

When to use TTL​

TTL fits any data that should not live forever and can be discarded once it is stale. Common uses are sessions and other temporary state, caches that clean themselves up, time-based invalidation, and short-lived resource tracking.

How expiration behaves​

Expiration is automatic and requires no manual cleanup — you never scan for and delete stale keys yourself. Expired keys are removed consistently across the cluster, so a key that has expired does not linger on some nodes and disappear on others.

In distributed mode, TTL is managed across all nodes and expiration is coordinated, so every client observes the same behavior. A key that has expired reads as absent regardless of which node a client is connected to.

TTL controls data, not ownership​

TTL answers one question: how long should this data exist? It does not track who is responsible for a resource. That distinction matters as soon as you move from caching to coordination.

tip

Keep TTL and leases in separate mental buckets. TTL controls the lifetime of data — when a value disappears. A lease controls ownership of a resource — who is currently responsible for it — and releases that ownership automatically when the owner stops renewing. When you need "delete this after a while", reach for TTL; when you need "exactly one owner, and recover if the owner dies", reach for a lease.

TTL is your first taste of lifecycle management. Clustron Zaris extends the idea with leases, which bind a resource's existence to an owner, and with coordination primitives that react to state changes.

Next steps​