Cassandra Clustering, in depth: clustering columns, on-disk order, slice queries, reversed reads and range deletes

What a clustering column is

Take this table:

CREATE TABLE chat.messages (
    channel_id  uuid,
    day         date,
    message_id  timeuuid,
    author_id   uuid,
    body        text,
    PRIMARY KEY ((channel_id, day), message_id)
) WITH CLUSTERING ORDER BY (message_id DESC);

The inner parentheses make (channel_id, day) a composite partition key: all messages for one channel on one day live in one partition, on the same replicas. message_id is the single clustering column. Inside the partition, rows are stored sorted by it, newest first because of the DESC order. A table can have several clustering columns; rows are then sorted by the first, ties broken by the second, and so on, exactly like sorting tuples.

Clustering columns also complete the row's identity. Two writes with the same partition key and the same clustering values address the same row, and Cassandra treats the second as an update, not a new row. That is why a clustering column must be unique within the partition for anything you want to keep separately. A timestamp clustering column is a classic trap: two events in the same millisecond silently become one row. A timeuuid avoids it because it carries a clock sequence and node component as well as the time, and it sorts by time.

Where the order lives

Cassandra never sorts at read time. The order is maintained at every stage of the write path, so reads only have to merge.

A write first goes to the commit log for durability and then into the memtable, an in-memory structure that keeps each partition's rows sorted by clustering key as they arrive. When the memtable flushes, it writes its partitions out in that order into an immutable SSTable. Each SSTable is therefore a sorted run: partitions in token order, and rows inside each partition in clustering order. Compaction merges several sorted runs into one and preserves both orders.

For a large partition, a read does not want to scan from the first row to find the slice it needs. SSTables keep a partition-level index that, for partitions above a size threshold, records index blocks: the first and last clustering value of each block of serialized rows and its offset. In Cassandra 4.0 the block size is set by column_index_size_in_kb with a default of 64 KiB; later versions renamed the key and have revisited the default, so read your own cassandra.yaml rather than trusting a number from a blog. A slice read binary-searches these blocks to land on the first block that can contain the start of the slice, then reads forward.

Because a partition is usually spread across the memtable and several SSTables, the read opens an iterator on each source positioned at the slice start and runs a k-way merge. Rows with the same clustering key from different sources are reconciled cell by cell, newest timestamp winning, and tombstones suppress older data. The output is already in order, so applying a LIMIT means simply stopping early.

The restriction rules, and why they exist

Because a partition is one sorted list, CQL only accepts clustering restrictions that translate into one contiguous range of that list, or a small set of ranges. The rules follow directly:

1. You can restrict clustering columns only as a prefix. With clustering columns (a, b, c) you may restrict a, or a and b, but not b alone, because rows with the same b are scattered across every value of a.
2. Within that prefix, every column must be restricted by equality or IN, except the last one, which may also take a range (<, <=, >, >=). A range on a followed by any restriction on b would describe many separate ranges.
3. Multi-column slices are allowed and are often what you actually need: WHERE pk = ? AND (a, b) > (?, ?) compares tuples in clustering order, which is exactly "everything after this position". It is the backbone of cursor paging over composite keys.
4. ORDER BY may only name clustering columns, and must either match the declared order or be its exact reverse for every column. You cannot sort by a regular column; there is no sort step to do it with.
5. Anything else needs ALLOW FILTERING, which tells Cassandra to read candidate rows and discard non-matching ones. Inside one partition of bounded size that can be acceptable; without a partition key restriction it scans the cluster.

Descending order and reversed reads

CLUSTERING ORDER BY sets the physical order. If most reads want newest first, declare the time column DESC so the most common query reads forward from the start of the partition. A query with the opposite ORDER BY is legal and returns correct results, but it is a reversed read: the storage engine walks the index blocks backwards and has to deserialize each block before emitting its rows in reverse. That costs more memory and CPU than a forward read, and the difference grows with partition size.

The order cannot be changed with ALTER TABLE. It is baked into every SSTable, so changing it means a new table and a data migration. Decide it from the dominant query, and if two access patterns genuinely need opposite orders at high volume, consider two tables written together rather than leaning on reversed reads.

Worked example: a chat history

Using the chat.messages table above, the screen that opens a channel needs the newest 50 messages for today:

SELECT message_id, author_id, body
FROM chat.messages
WHERE channel_id = ? AND day = '2026-10-01'
LIMIT 50;

This touches one partition, seeks to its start and reads forward. When the user scrolls up, the client sends the oldest message_id it holds, and the next page is a slice strictly after it in clustering order, which with DESC means strictly older:

SELECT message_id, author_id, body
FROM chat.messages
WHERE channel_id = ? AND day = ? AND message_id < ?
LIMIT 50;

To jump to a time window, use the timeuuid helper functions, which build the smallest and largest possible timeuuid for a timestamp: message_id >= minTimeuuid('2026-10-01 09:00+0000') AND message_id < maxTimeuuid('2026-10-01 10:00+0000'). When a page empties a partition, the client moves to the previous day partition and repeats; the day bucket is what keeps any single partition from growing without bound, and sizing that bucket is covered in Cassandra time-series modeling.

A quick size check for the bucket: a busy channel with 200,000 messages a day at roughly 300 bytes per row is around 60 MB per partition before compression. That is workable, but at the upper end of what most teams like; a channel ten times busier should bucket by hour.

Paging from application code

There are two ways to page. Driver paging lets the server return a page plus an opaque paging state that encodes where the scan stopped; you hand it back to get the next page. Cursor paging uses your own clustering values, as above. Driver paging is ideal for batch jobs that read a whole partition; cursor paging is better for user interfaces because the cursor is meaningful, survives schema-compatible deploys and can be put in a URL. With the Python driver:

from cassandra.cluster import Cluster
from cassandra.query import SimpleStatement

session = Cluster(["10.0.0.11"]).connect("chat")

# 1. Driver paging: read a whole partition in pages of 500.
stmt = SimpleStatement(
    "SELECT message_id, body FROM messages WHERE channel_id = %s AND day = %s",
    fetch_size=500,
)
result = session.execute(stmt, (channel_id, day))
while True:
    for row in result.current_rows:
        process(row)
    if not result.paging_state:
        break
    result = session.execute(stmt, (channel_id, day), paging_state=result.paging_state)

# 2. Cursor paging for a UI: prepared once, bound per request.
older = session.prepare(
    "SELECT message_id, author_id, body FROM messages "
    "WHERE channel_id = ? AND day = ? AND message_id < ? LIMIT 50"
)
page = list(session.execute(older, (channel_id, day, cursor)))
next_cursor = page[-1].message_id if page else None

Treat the driver's paging state as opaque and short-lived; it is tied to the query and is not meant to be stored or shown to users. For composite clustering keys, the cursor is the full tuple of the last row's clustering values and the query uses a tuple slice, (a, b) < (?, ?), so that rows sharing a are not skipped or repeated.

Range deletes and tombstones in clustering space

Because rows are ordered, Cassandra can delete a whole range of them with one marker. DELETE FROM chat.messages WHERE channel_id = ? AND day = ? AND message_id < ? writes a single range tombstone covering every clustering value below the bound. It is cheap to write and, during reads, suppresses every older cell in its range.

The danger is the pattern that produces many tombstones at the front of the slice you keep reading. A queue modelled as "insert at the end, delete from the front, always read from the front" makes every read walk past all the deleted rows' tombstones before reaching live data, until compaction purges them after gc_grace_seconds. Cassandra logs a warning when a read scans more than tombstone_warn_threshold tombstones (1,000 by default) and aborts it past tombstone_failure_threshold (100,000 by default). The fix is in the model: read from a stored cursor rather than the front, or delete a whole range with one range tombstone instead of row by row, or rotate partitions so old ones are simply never read again.

TTL-expired rows behave like tombstones too. In time-ordered tables with TTLs, compaction strategy choice decides whether expired data disappears in whole SSTables or lingers as tombstones mixed with live rows.

Failure modes

• Unbounded partitions. Clustering makes it tempting to put everything for one entity in one partition. Partitions that grow forever become slow to read, repair and compact. Always ask what bounds the partition.
• Silent overwrites. A clustering key that is not unique (a millisecond timestamp, a non-unique name) merges distinct events into one row. Add a tie-breaker column or use a timeuuid.
• Reversed reads on hot paths. The data model chose ASC, the main screen reads DESC. Results are correct, latency is not. Fix the order in a new table.
• ALLOW FILTERING creeping in. Usually it means a query the table was not designed for. Add a table keyed for that query, or restrict it to a bounded partition and accept the cost knowingly.
• Tombstone walls. Reading from the front of a partition you keep deleting from. Watch the warning logs and per-table tombstone metrics.
• Mutable sort fields. Using a value that changes, such as a score or status, as a clustering column turns every change into a delete and an insert and leaves a tombstone each time. Use a separate table rebuilt periodically, or sort in the application if the set is small.

Trade-offs

Clustering gives you one sort order per table for free. Every additional order costs either another table, written at the same time and kept consistent by the application, or a secondary index with its own read cost, as discussed in Cassandra secondary indexes. Materialized views were designed for this but remain experimental and are disabled by default in recent versions. For most teams, a denormalized second table with a clear owner of the write path is the reliable answer.