Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 30 ยท How Cassandra Works Inside

Deletes, TTL and tombstones

Learn how Cassandra deletes data with tombstones, what gc_grace_seconds protects, why zombie data returns, and how to avoid tombstone-heavy reads.

In a database that edits files in place, a delete removes bytes. Cassandra never edits an SSTable, so a delete cannot remove anything from the files that hold the old data. Instead, a delete is a write: it stores a small marker, a tombstone, with a timestamp. During reads, the tombstone wins over older data with a lower timestamp, so the value appears gone. Much later, compaction physically throws both away.

That single design decision explains some of the most famous Cassandra incidents: reads that slow to a crawl because they wade through thousands of tombstones, and deleted rows that mysteriously come back from the dead. This lesson explains both and shows how to design around them. As in the other lessons of this track, the CQL is read-only, and the JavaScript stand-ins model the idea with toy data. Their counts are not Cassandra measurements.

You will get more from this lesson if you have read about the write path, reads and compaction and replication and repair.

What creates a tombstone

SQL
-- A cell tombstone: one column of one row
DELETE phone FROM shop.users WHERE user_id = ?;

-- A row tombstone: a whole row
DELETE FROM shop.orders WHERE user_id = ? AND order_day = '2026-03-03' AND order_id = ?;

-- A range tombstone: many rows with one marker
DELETE FROM shop.orders WHERE user_id = ? AND order_day = '2026-03-03' AND order_id < ?;

-- A partition tombstone: the whole partition
DELETE FROM shop.orders WHERE user_id = ? AND order_day = '2026-03-03';

Notice that the number of tombstones depends on how you delete. Deleting a thousand rows one at a time writes a thousand tombstones; deleting them with one range or partition delete writes one. Other operations create tombstones quietly:

  • Writing null. INSERT ... VALUES (..., null) stores a tombstone for that column. Leave the column out of the statement (or use the "unset" feature of your driver) when you have no value.
  • TTL expiry. A cell written with USING TTL 3600 becomes a tombstone-like marker once it expires.
  • Replacing a non-frozen collection. Assigning a whole new set or list first deletes the old content with a tombstone.
flowchart LR
    A["SSTable 1<br/>order 7 = shipped<br/>ts 100"] --> R["Read merges both"]
    B["SSTable 2<br/>order 7 = TOMBSTONE<br/>ts 200"] --> R
    R --> O["Result: no row<br/>(ts 200 beats ts 100)"]

The tombstone hides the older value but does not erase it; the old row still sits in SSTable 1 until compaction.

gc_grace_seconds: the safety window

Why not purge a tombstone immediately? Because a copy of the data might exist on a replica that has not yet heard about the delete. Suppose replica C was down when you deleted a row. If A and B throw away their tombstones right away, then when C returns, it still holds the old row, and the next repair or read sees "C has it, A and B do not" and copies the row back to them. The delete is undone.

The table option gc_grace_seconds (default 864,000 seconds, or ten days) is the promise that bridges this gap: a tombstone is kept for at least this long before compaction may purge it, and in that time every replica must have received it, through the write itself, a hint, read repair or nodetool repair. The rule of operation follows directly: run repair on every node at least once per gc_grace_seconds.

SQL
ALTER TABLE shop.orders WITH gc_grace_seconds = 864000;

Lowering the value shrinks tombstone lifetime but shortens the time you have to repair. Do not lower it unless repairs run much more often, or the data is only ever written with a TTL and never deleted explicitly.

Stand-in 1: zombie data

Two replicas, n1 and n2, hold the same row. n2 goes down for a long time, a delete reaches only n1, n1 purges its tombstone after the grace period, and when n2 returns, a repair copies the "deleted" row back. A second timeline runs repair inside the grace window. Time is in days; the rule used by repair here is simply "newest timestamp wins".

JS How deleted data comes back from the dead

Press Run (or Ctrl + Enter) to see the console output here.

No output.

In the first timeline the row order:7 is back on both replicas after the repair: the tombstone was purged before n2 learned about it, so the old row looks like new, unopposed data. In the second timeline, repair ran on day 5, inside the grace period, so n2 received the tombstone and both replicas could purge it safely.

Tombstones slow reads

A tombstone is not free: it occupies space and, more importantly, it must be read and skipped. A query that scans a range of a partition has to step over every tombstone in that range on its way to the live rows it wants. Cassandra protects itself with two settings in cassandra.yaml: tombstone_warn_threshold (default 1,000) writes a warning to the log, and tombstone_failure_threshold (default 100,000) aborts the query.

The classic cause is using a table as a queue: producers insert jobs, consumers read the oldest and delete them. The partition fills with tombstones at the front, and each "give me the first job" query has to skip all of them.

Stand-in 2: reading past tombstones

A partition holds 5,000 jobs. Workers have processed and deleted the first 4,990. The program reads the first 10 live jobs under three different deletion styles and counts how many tombstones the read stepped over.

JS Queue anti-pattern: counting skipped tombstones

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Deleting row by row forces the reader past 4,990 tombstones, which is above the warning threshold. One range tombstone costs the reader a single step. The bucketed design avoids the problem altogether because expired work lives in partitions you stop reading.

Designing to avoid tombstone trouble

  • Prefer not to delete. Model data as append-only facts, and filter by status or time in your queries.
  • Delete big pieces at once. A partition delete or a range delete costs one tombstone.
  • Use TTL plus time buckets for data that expires, together with a time-window compaction strategy. See Time-series and bucketing patterns.
  • Never use Cassandra as a queue. A message broker or a database built for queues is the better tool.
  • Do not write nulls. Leave out columns that have no value.
  • Run repair on schedule so that every replica sees tombstones before gc_grace_seconds runs out.
  • Watch the logs and metrics for tombstone warnings; they point at the exact table.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a DELETE statement store in Cassandra?

    SSTables are immutable, so a delete is a write of a tombstone. Compaction removes the data later.
  2. 2. Why does Cassandra keep tombstones for gc_grace_seconds before purging them?

    If a tombstone were purged while a replica still held the old value, repair would treat that old value as live data and copy it back.
  3. 3. Which of these writes a tombstone without any DELETE statement?

    An explicit null means 'no value', which Cassandra records as a tombstone. Omit the column instead.
  4. 4. A table used as a job queue gets slower as jobs are consumed and deleted. What is the likely reason?

    Deleted jobs leave tombstones at the start of the partition, and every read for the oldest live job has to step over them.
  5. 5. Which delete style creates the fewest tombstones for 1,000 rows of one partition?

    A range or partition delete is a single tombstone that covers all the rows, instead of one per row.

Summary

  • A delete is a write: a tombstone with a timestamp hides older data until compaction purges both.
  • Tombstones come from deletes, null writes, expired TTLs and replaced collections.
  • gc_grace_seconds (ten days by default) is the window in which all replicas must learn of the delete; run repair within it, or deleted data can return.
  • Reads must skip tombstones, so queue-like tables and per-row deletes get slow; Cassandra logs a warning at 1,000 and aborts at 100,000 by default.
  • Design for append-only data, partition or range deletes, and TTL with time buckets. The stand-ins here are models; real purge rules also check overlapping SSTables.

Next: Lightweight transactions, batches and counters.