Apache Cassandra
Collections (SET, LIST, MAP) & User-Defined Types
Learn how to model structured, multi-valued, and nested data using CQL collections and user-defined types.
CQL provides three built-in collection types — SET, LIST, and MAP — for storing small, bounded groups of values within a single column, avoiding the need for a separate child table for simple cases. A SET stores unique unordered values, a LIST stores an ordered sequence of values (allowing duplicates), and a MAP stores key-value pairs.
Collections and UDTs are like allowing a filing cabinet drawer (a row) to contain a small labeled envelope with a few related sub-items (like a set of phone numbers or a small address card), instead of requiring every tiny detail to have its own separate drawer.
Key Concepts
1
User-Defined Types (UDTs) let you define a custom structured type (similar to a struct) that can be used as a column type, nested inside collections, or even nested within other UDTs. This is useful for grouping related fields together (like an address with street, city, and zip) without flattening everything into separate top-level columns or creating an entirely separate table.
User-Defined Types (UDTs)
2
Both collections and UDTs come with important caveats: collections are generally intended for small sets of values (typically fewer than a few hundred items), since the entire collection is read and (in most cases) written as a whole, or with limited support for individual element updates depending on the collection type. Frozen collections/UDTs (frozen<...>) are serialized as a single immutable blob, which is required when nesting collections inside other collections, but that means you must rewrite the entire value to change a single element.
smallfrozen<...>
3
For large or unbounded multi-valued data (e.g., "all orders for a user" numbering in the thousands), a separate table with clustering columns is almost always the better modeling choice over a collection.