Unravel โบ Java concepts โบ NoSQL and caches
Cassandra and wide-column modelling
Cassandra spreads data over many nodes by a partition key and is built for huge write volumes and predictable reads.
At a glance
A city with many post offices where each address is assigned to exactly one by its postcode.
- 1The primary key has two parts: the partition key (which nodes store the row) and clustering columns (the sort order inside a partition)A query must provide the partition key.
- 2Tables are modelled per query, with data duplicated across tables: orders_by_customer and orders_by_day hold the same facts for different access paths
- 3CqlSession runs prepared statements (session.prepare(...).bind(...))Always prepare statements that repeat; the parse is done once.
- 4Consistency is a per-request choice: LOCAL_QUORUM reads and writes give strong consistency inside a data centre, ONE is faster but may return stale data
- Unbounded partitions are the main failure mode
- ALLOW FILTERING, secondary indexes on high-cardinality columns and large IN lists create cluster-wide scans
- Writes go to a commit log and an in-memory memtable and are acknowledged without reading anything, which is why writes are so fast
PreparedStatement insert = session.prepare( "insert into readings_by_sensor_day (sensor_id, day, ts, value) values (?, ?, ?, ?)");session.execute(insert.bind(sensorId, day, Instant.now(), value) .setConsistencyLevel(DefaultConsistencyLevel.LOCAL_QUORUM));- line 4 uses ConsistencyLevel, the core of Cassandra and wide-column modelling
Read the full explanation (about 2 min)
Cassandra spreads data over many nodes by a partition key and is built for huge write volumes and predictable reads. In exchange you design tables around the queries you will run and give up joins and ad-hoc filters.
A mental model
A city with many post offices where each address is assigned to exactly one by its postcode. Finding mail for one postcode is instant; asking "all mail from anyone called Smith" means visiting every office.
How it works
The primary key has two parts: the partition key (which nodes store the row) and clustering columns (the sort order inside a partition). A query must provide the partition key.
Tables are modelled per query, with data duplicated across tables: orders_by_customer and orders_by_day hold the same facts for different access paths.
CqlSession runs prepared statements (session.prepare(...).bind(...)). Always prepare statements that repeat; the parse is done once.
Consistency is a per-request choice: LOCAL_QUORUM reads and writes give strong consistency inside a data centre, ONE is faster but may return stale data.
Going deeper
Unbounded partitions are the main failure mode. A partition key like sensor_id collects data forever; add a time bucket (sensor_id, day) to keep each partition under a few hundred MB.
ALLOW FILTERING, secondary indexes on high-cardinality columns and large IN lists create cluster-wide scans. Treat them as a design smell.
Deletes write tombstones that linger for gc_grace_seconds; queues modelled as insert-then-delete suffer from tombstone overload. Use TTL and time-bucketed partitions instead.
Under the hood
Writes go to a commit log and an in-memory memtable and are acknowledged without reading anything, which is why writes are so fast. Memtables flush to immutable SSTables that are merged by compaction. Reads consult memtable, bloom filters and the relevant SSTables and merge results by timestamp (last write wins).
Common mistakes
- Modelling tables like a relational schema.
- Unbounded partitions.
- Using ALLOW FILTERING in production queries.
- Unprepared statements in hot paths.
How Unravel recognises it
When you paste code, Unravel looks for these signs of cassandra and wide-column modelling. Spotting them yourself is a good habit when you read unfamiliar code:
- Annotations:
@PrimaryKeyColumn@PrimaryKey@CassandraType - Types:
CqlSessionCassandraTemplateCassandraOperationsCassandraRepositorySimpleStatementBoundStatementPrimaryKeyTypeBatchStatementConsistencyLevelDefaultConsistencyLevelCqlSessionBuilderAsyncResultSetReactiveCassandraTemplateCassandraTypeMapper
Part of a learning path
- Data stores beyond SQL ยท previous: Elasticsearch and OpenSearch search ยท next: DynamoDB access
Related concepts
Frequently asked questions
What is Cassandra and wide-column modelling?
Cassandra spreads data over many nodes by a partition key and is built for huge write volumes and predictable reads. In exchange you design tables around the queries you will run and give up joins and ad-hoc filters.
What are the most common mistakes with Cassandra and wide-column modelling?
Modelling tables like a relational schema. Unbounded partitions. Using ALLOW FILTERING in production queries. Unprepared statements in hot paths.
How can I see Cassandra and wide-column modelling in real code?
Paste your own Java into Unravel and it will point out where cassandra and wide-column modelling appears, explain how it works at the detail level you choose, and draw the flow of the code around it.