Tuples and User-Defined Types for Structured Values and Schema Evolution

Learning outcomes

AtlasMart needs shipping addresses and geographic coordinates in several query tables. A tuple can pack a small positional structure, while a user-defined type (UDT) gives named fields and a reusable schema inside one keyspace. Those conveniences have different mutation and evolution contracts, so they should be chosen deliberately rather than because they look object-like.

1. Tuple and UDT solve different structure problems

A tuple has ordered typed positions such as tuple<double,double>. Its meaning depends on an external convention—“position 0 is latitude, position 1 is longitude”—and tuple values are effectively frozen as one value. A UDT has named fields such as line1, city, and country. UDTs belong to a keyspace and can be reused by tables in that keyspace. In Cassandra 5.0, a UDT containing only non-collection fields can be stored non-frozen, allowing individual field mutation; a frozen UDT is treated as one cell and replaced as a whole.

2. Lab: create, mutate, and evolve a UDT

# Verify the shared course lab if it already exists.docker exec atlasmart-cass-1 nodetool versiondocker exec atlasmart-cass-1 nodetool status# Standalone local recreation path. Skip resources that already exist.docker network inspect atlasmart-cassandra >/dev/null 2>&1 || docker network create atlasmart-cassandradocker volume create atlasmart-cass-1-datadocker volume create atlasmart-cass-2-datadocker volume create atlasmart-cass-3-datadocker inspect atlasmart-cass-1 >/dev/null 2>&1 || docker run -d --name atlasmart-cass-1 --hostname atlasmart-cass-1 --network atlasmart-cassandra -e CASSANDRA_CLUSTER_NAME=atlasmart-course -e CASSANDRA_DC=dc1 -e CASSANDRA_RACK=rack1 -e CASSANDRA_ENDPOINT_SNITCH=GossipingPropertyFileSnitch -e CASSANDRA_NUM_TOKENS=16 -v atlasmart-cass-1-data:/var/lib/cassandra cassandra:5.0.9# Wait for node 1 to answer before starting peers.docker exec atlasmart-cass-1 nodetool statusdocker inspect atlasmart-cass-2 >/dev/null 2>&1 || docker run -d --name atlasmart-cass-2 --hostname atlasmart-cass-2 --network atlasmart-cassandra -e CASSANDRA_CLUSTER_NAME=atlasmart-course -e CASSANDRA_DC=dc1 -e CASSANDRA_RACK=rack2 -e CASSANDRA_ENDPOINT_SNITCH=GossipingPropertyFileSnitch -e CASSANDRA_NUM_TOKENS=16 -e CASSANDRA_SEEDS=atlasmart-cass-1 -v atlasmart-cass-2-data:/var/lib/cassandra cassandra:5.0.9docker inspect atlasmart-cass-3 >/dev/null 2>&1 || docker run -d --name atlasmart-cass-3 --hostname atlasmart-cass-3 --network atlasmart-cassandra -e CASSANDRA_CLUSTER_NAME=atlasmart-course -e CASSANDRA_DC=dc1 -e CASSANDRA_RACK=rack3 -e CASSANDRA_ENDPOINT_SNITCH=GossipingPropertyFileSnitch -e CASSANDRA_NUM_TOKENS=16 -e CASSANDRA_SEEDS=atlasmart-cass-1 -v atlasmart-cass-3-data:/var/lib/cassandra cassandra:5.0.9# Continue only after all nodes show UN.docker exec atlasmart-cass-1 nodetool statusdocker exec atlasmart-cass-1 cqlsh -e "CREATE KEYSPACE IF NOT EXISTS atlasmart_types WITH replication = {'class':'NetworkTopologyStrategy','dc1':3};"docker exec atlasmart-cass-1 cqlsh -e "DESCRIBE KEYSPACE atlasmart_types"

CREATE TYPE atlasmart_types.address_v1 (    line1 text,    city text,    country text);CREATE TABLE atlasmart_types.orders_structured (    order_id uuid PRIMARY KEY,    ship_to atlasmart_types.address_v1,    ship_to_snapshot frozen<atlasmart_types.address_v1>,    drop_point tuple<double,double>,    total decimal) WITH compaction = {'class':'UnifiedCompactionStrategy'};DESCRIBE TYPE atlasmart_types.address_v1;DESCRIBE TABLE atlasmart_types.orders_structured;INSERT INTO atlasmart_types.orders_structured(order_id,ship_to,ship_to_snapshot,drop_point,total)VALUES(aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa, {line1:'1 Atlas Ave',city:'Tehran',country:'IR'}, {line1:'1 Atlas Ave',city:'Tehran',country:'IR'}, (35.6892,51.3890), 49.90);SELECT * FROM atlasmart_types.orders_structured;

-- Non-frozen UDT: mutate one field.UPDATE atlasmart_types.orders_structuredSET ship_to.city = 'Baku'WHERE order_id=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa;-- Frozen UDT and tuple: replace the whole value.UPDATE atlasmart_types.orders_structuredSET ship_to_snapshot = {line1:'1 Atlas Ave',city:'Baku',country:'AZ'},    drop_point = (40.4093,49.8671)WHERE order_id=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa;ALTER TYPE atlasmart_types.address_v1 ADD postal_code text;DESCRIBE TYPE atlasmart_types.address_v1;SELECT ship_to,ship_to_snapshot,drop_point FROM atlasmart_types.orders_structured;

Existing values predate postal_code, so the new field is expected to read as NULL until written. This is a schema-evolution fact, not automatic backfill. Current CQL supports adding and renaming UDT fields; arbitrary type changes were removed from modern CQL, so incompatible evolution requires a migration strategy.

3. Driver decoding preserves named and positional structure

Row row = session.execute(    "SELECT ship_to, ship_to_snapshot, drop_point FROM atlasmart_types.orders_structured WHERE order_id=?",    UUID.fromString("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")).one();UdtValue live = row.getUdtValue("ship_to");String city = live.getString("city");String postalCode = live.getString("postal_code"); // null until writtenUdtValue snapshot = row.getUdtValue("ship_to_snapshot");TupleValue point = row.getTupleValue("drop_point");double latitude = point.getDouble(0);double longitude = point.getDouble(1);

4. Production judgment

Use tuples when the structure is tiny, stable, and positional meaning is obvious to every consumer. Use UDTs when named fields materially improve correctness and several query tables share the same embedded value shape. Decide frozen versus non-frozen from mutation granularity: snapshots often belong frozen; mutable profile-like structures may benefit from field-level updates if their field types permit it. Keep UDTs from becoming a deeply nested object graph. Every extra nested value increases schema coupling, driver codec surface, migration testing, and cross-team coordination.

Verification checklist

• DESCRIBE TYPE shows the expected keyspace-scoped field schema.
• A non-frozen UDT field can be updated without replacing unrelated fields.
• The frozen snapshot and tuple are replaced as whole values.
• After ALTER TYPE ADD, historical rows expose NULL for the new field until updated.
• Optional driver decoding uses UdtValue/TupleValue APIs and preserves nullability.

# Destructive only to this disposable chapter keyspace.docker exec atlasmart-cass-1 cqlsh -e "DROP KEYSPACE IF EXISTS atlasmart_types;"# Keep shared course containers for Chapter 09, or remove them for a full reset:# docker rm -f atlasmart-cass-1 atlasmart-cass-2 atlasmart-cass-3# docker volume rm atlasmart-cass-1-data atlasmart-cass-2-data atlasmart-cass-3-data# docker network rm atlasmart-cassandra

Summary and next bridge

Tuples are positional frozen structures; UDTs add names and controlled evolution. Next we focus directly on frozen versus multi-cell storage, nested types, and how mutation granularity changes tombstone and write behavior.

Authoritative references

• CQL data types — scalar, collection, tuple, user-defined type, frozen, and literal semantics.
• Creating collections — bounded collection guidance and current collection guardrails.
• CQL data definition — static-column behavior, table/type definitions, and schema restrictions.
• CREATE TABLE reference — frozen/non-frozen UDT and static-column examples.
• Tombstones — deletion markers, grace, reads, and compaction implications.
• Apache Cassandra downloads — current server and Java-driver release baselines.