TTL (Time-To-Live)

Cassandra and ScyllaDB can automatically expire data after a given number of seconds. coodie exposes TTL through the ttl parameter on write operations and through the QuerySet.ttl() chain method.

Setup

from coodie.fields import PrimaryKey
from pydantic import Field
from typing import Annotated
from uuid import UUID, uuid4
from datetime import datetime

class Session(Document):
    token: Annotated[str, PrimaryKey()]
    user_id: UUID
    created_at: datetime

    class Settings:
        name = "sessions"

Save with TTL

Pass ttl=<seconds> to save() to make the row expire:

session = Session(
    token="abc123",
    user_id=uuid4(),
    created_at=datetime.now(),
)

session.save(ttl=3600)              # expires in 1 hour — sync
# await session.save(ttl=3600)      # async

Generated CQL:

INSERT INTO sessions (token, user_id, created_at)
VALUES (?, ?, ?)
USING TTL 3600;

Insert with TTL

insert() also accepts ttl:

session.insert(ttl=300)             # expires in 5 minutes — sync
# await session.insert(ttl=300)     # async

Update with TTL

Apply a TTL when updating specific fields:

session.update(ttl=7200, user_id=new_user_id)       # sync
# await session.update(ttl=7200, user_id=new_user_id)  # async

Generated CQL:

UPDATE sessions USING TTL 7200
SET user_id = ?
WHERE token = ?;

QuerySet TTL

Set the TTL on the query chain for create() or update() calls:

Session.find().ttl(3600).create(
    token="xyz789",
    user_id=uuid4(),
    created_at=datetime.now(),
)

Or use using() to set TTL alongside other options:

Session.find(token="abc123").using(ttl=7200).update(
    user_id=new_user_id,
)

How TTL Works

Note

TTL is applied per cell, not per row. When you save() with a TTL, every non-key column gets the same TTL. When you update() with a TTL, only the columns you set in that update get the TTL. Key columns never expire.

After the TTL elapses, the affected cells become tombstones and are eventually removed during compaction. Reads will return None (or the column default) for expired cells.

For more details on TTL mechanics, see the database documentation:

What’s Next?