Apache Cassandra
Partition Keys & Clustering Columns
Learn how partition keys determine data placement and clustering columns control sort order within a partition.
In Cassandra, the primary key of a table is composed of two parts: the partition key and optional clustering columns. The partition key determines which node(s) store the data by hashing its value into a token, while clustering columns determine the on-disk sort order of rows *within* that partition.
The partition key is like the file cabinet a folder is stored in, and the clustering columns are like the alphabetical order of the documents within that specific folder.
Key Concepts
1
All rows sharing the same partition key value are stored together on the same set of replica nodes, contiguous on disk, sorted by the clustering columns. This is fundamentally different from relational databases, where physical storage location is abstracted away from the developer.
2
Choosing a good partition key is one of the most important data modeling decisions in Cassandra. A well-chosen key distributes data evenly across the cluster (avoiding hotspots) while still grouping data that is commonly queried together — since Cassandra queries are most efficient when they target a single partition.
hotspots
3
Clustering columns let you model one-to-many relationships naturally, such as storing all sensor readings for a device sorted by timestamp, without needing a JOIN.