Working with Collections (Lists, Sets, Maps) in Cassandra

Collection Types in Cassandra

Cassandra provides three collection types -- list, set, and map -- that allow you to store multiple values in a single column. Collections are useful for denormalized data that would require a join table in a relational database. However, they are designed for small amounts of data (hundreds of items, not thousands).

Sets

A set stores unique, unordered values. It is ideal for tags, categories, or any collection where duplicates should be eliminated automatically.

-- Create table with a set column
CREATE TABLE articles (
  article_id UUID PRIMARY KEY,
  title TEXT,
  tags SET<TEXT>
);

-- Insert with set values
INSERT INTO articles (article_id, title, tags)
VALUES (uuid(), 'Intro to Cassandra', {'database', 'nosql', 'cassandra'});

-- Add elements to a set
UPDATE articles
SET tags = tags + {'distributed', 'tutorial'}
WHERE article_id = 550e8400-e29b-41d4-a716-446655440000;

-- Remove elements from a set
UPDATE articles
SET tags = tags - {'tutorial'}
WHERE article_id = 550e8400-e29b-41d4-a716-446655440000;

Lists

A list stores ordered values and allows duplicates. Use lists when order matters or when you need to allow repeated values.

-- Create table with a list column
CREATE TABLE playlists (
  playlist_id UUID PRIMARY KEY,
  name TEXT,
  songs LIST<TEXT>
);

-- Insert with list values
INSERT INTO playlists (playlist_id, name, songs)
VALUES (uuid(), 'Road Trip', ['Song A', 'Song B', 'Song C']);

-- Append to a list
UPDATE playlists
SET songs = songs + ['Song D']
WHERE playlist_id = 550e8400-e29b-41d4-a716-446655440000;

-- Prepend to a list
UPDATE playlists
SET songs = ['Song Z'] + songs
WHERE playlist_id = 550e8400-e29b-41d4-a716-446655440000;

-- Replace by index
UPDATE playlists
SET songs[1] = 'New Song B'
WHERE playlist_id = 550e8400-e29b-41d4-a716-446655440000;

Maps

A map stores key-value pairs. It is perfect for metadata, configuration, or any labeled data where you need to look up values by key.

-- Create table with a map column
CREATE TABLE user_profiles (
  user_id UUID PRIMARY KEY,
  name TEXT,
  preferences MAP<TEXT, TEXT>
);

-- Insert with map values
INSERT INTO user_profiles (user_id, name, preferences)
VALUES (uuid(), 'Alice', {'theme': 'dark', 'language': 'en', 'timezone': 'UTC'});

-- Add or update map entries
UPDATE user_profiles
SET preferences['notifications'] = 'enabled'
WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;

-- Remove a map entry
DELETE preferences['timezone']
FROM user_profiles
WHERE user_id = 550e8400-e29b-41d4-a716-446655440000;

Frozen Collections

When using collections inside other collections or as part of a primary key, you must use the FROZEN keyword. A frozen collection is serialized as a single value and cannot be partially updated.

-- Frozen collection as a clustering key
CREATE TABLE events_by_tags (
  event_date DATE,
  tags FROZEN<SET<TEXT>>,
  event_id UUID,
  title TEXT,
  PRIMARY KEY (event_date, tags, event_id)
);

-- Nested collections require FROZEN
CREATE TABLE complex_data (
  id UUID PRIMARY KEY,
  matrix LIST<FROZEN<LIST<INT>>>
);

Key Takeaways

• Use sets for unique unordered values, lists for ordered values, and maps for key-value pairs.
• Collections are best for small datasets (up to a few hundred items).
• Sets and maps support element-level additions and removals; lists also support index-based updates.
• Use FROZEN for collections inside primary keys or nested within other collections.