TTL: Data That Expires
Some data is only useful for a short time. A login session should end after a few hours. A verification code should stop working after a few minutes. In many databases, you write a cleanup job that deletes old rows.
In Cassandra, you can give data a TTL (time to live) instead. A TTL is a number of seconds. When that time is over, Cassandra removes the data by itself.
Syntax
INSERT INTO table_name (columns)
VALUES (values)
USING TTL seconds;
UPDATE table_name USING TTL seconds
SET column = value
WHERE primary_key = value;
In an INSERT, USING TTL goes at the end. In an UPDATE, it goes right after the table name.
Example: a session that ends after one hour
The sessions table has two columns, session_token and username. One session is already in it, for alice. Add a session for bob that lasts one hour (3600 seconds):
INSERT INTO sessions (session_token, username)
VALUES ('abc123', 'bob')
USING TTL 3600;
SELECT session_token, username, TTL(username)
FROM sessions;
Output:
session_token | username | ttl(username)
---------------+----------+---------------
tok-1 | alice | null
abc123 | bob | 3600
(2 rows)
The TTL() function shows how many seconds a value has left. Bob's value has 3600 seconds left, because it was just written. (If a second passes between the two statements, you may see 3599.) This number goes down by one every second. When it reaches zero, the value is removed. Bob's whole row was inserted with the TTL, so after one hour the whole row is gone.
Alice's value shows null. It was written without a TTL, so it never expires.
Example: TTL with UPDATE
An UPDATE can set a TTL too. Give bob's session only 60 seconds:
UPDATE sessions USING TTL 60
SET username = 'bob'
WHERE session_token = 'abc123';
SELECT username, TTL(username) FROM sessions
WHERE session_token = 'abc123';
Output:
username | ttl(username)
----------+---------------
bob | 60
(1 rows)
The TTL belongs to the values that one statement writes. A new write gives the value a new TTL. If you write the value again without USING TTL, the value no longer expires:
UPDATE sessions
SET username = 'bob'
WHERE session_token = 'abc123';
SELECT username, TTL(username) FROM sessions
WHERE session_token = 'abc123';
Output:
username | ttl(username)
----------+---------------
bob | null
(1 rows)
A default TTL for a table
If every row of a table should expire, set a default TTL when you create the table. Then every write gets this TTL, unless it gives its own:
CREATE TABLE codes (
email text PRIMARY KEY,
code text
) WITH default_time_to_live = 600;
INSERT INTO codes (email, code)
VALUES ('[email protected]', '4821');
SELECT email, code, TTL(code) FROM codes;
Output:
email | code | ttl(code)
-------------------+------+-----------
[email protected] | 4821 | 600
(1 rows)
The INSERT had no USING TTL, but the code still expires after 600 seconds (10 minutes).
Good to know
When a value expires, Cassandra turns it into a tombstone, just like a DELETE does. That is fine for small data like sessions. But if a table has a huge number of values that expire, it collects many tombstones, and reads get slower.
You don't need a cleanup job. The TTL is stored with the data, so every node knows when the data should go.
In the exercise, insert a session for maya that expires after one hour.