AWS Database Blog

Announcing frozen collections for Amazon Keyspaces

Amazon Keyspaces (for Apache Cassandra) is a scalable, highly available, and managed Apache Cassandra-compatible database service. With Amazon Keyspaces, you can run your Cassandra workloads on AWS using the same Cassandra application code and developer tools that you’re currently using.

Today, we are introducing support for frozen collections in Amazon Keyspaces. With this launch, you can use the frozen keyword and store collection data types (like lists, sets, and maps) as a single, immutable value. In this post, we discuss the benefits and use cases of this new feature, and demonstrate how to create and use frozen collections in Amazon Keyspaces.

Benefits of using frozen collections

Some of the benefits of using frozen collections in Amazon Keyspaces include:

  • Parity with open-source Cassandra – Frozen collections in Amazon Keyspaces offer the same functionality as offered by open-source Cassandra. You can run your Cassandra applications that use frozen collections without any refactoring on Amazon Keyspaces. Moreover, using the AWS Management Console, you can visually define frozen collections, including nested collections.
  • Avoiding partial updates – When a collection is declared as frozen, it becomes an immutable entity. In other words, individual elements or fields within that collection or tuple can’t be updated independently. Instead, you have to replace the entire value of the collection or tuple. If your use case requires that a collection’s value be replaced in its entirety, you can consider using a frozen collection.
  • Nested collections – Application data often exists in hierarchical relationships and in order to model these relationships in intuitive and direct ways, support for nesting data types is needed. With support for frozen collections, you can now nest collections within other collections and model the hierarchical relationships that naturally occur in your data. Your applications can use the data in more intuitive ways, making the application code more maintainable.
  • Collections as primary keys – By declaring a collection column as frozen, you can include that column in the primary key. Frozen collections enable use cases where you need to directly index the database on a group of values without having to implement complicated design patterns.

Solution overview

In the following sections, we demonstrate how to define your table that contains frozen collections and how to perform create, insert, update, and select operations on the different types of frozen collections (SET, LIST, and MAP). Examples also provide details on common errors, such as when you try to partially update the value of a frozen collection. You can create a new table using the console or CQL APIs. Amazon Keyspaces also supports AWS native approaches to resource creation such as the AWS SDK and AWS CloudFormation.

Create a new table using the console

To create a new table using the console, complete the following steps:

  1. On the Amazon Keyspaces console, choose Tables in the navigation pane.
  2. Choose Create table.
  3. For Table name, enter an identifier or use the name product_tags.
  4. Select Default settings for the table.
  5. Choose Create table.

You should see your new table in the list of available tables.

Create a new table using CQL APIs

In addition to using the console, you can create a table using CQL APIs. If you have already created your table, you can skip this step. For this post, we use the built-in query editor on the Amazon Keyspaces console. You can use any Cassandra-compatible tool or driver to use the CQL APIs specified in this section.

Navigate to the CQL editor and enter the following CREATE TABLE statement:

CREATE TABLE "frozen_example"."product_tags"(
    "product_id" UUID,
    "tags" FROZEN<SET<TEXT>>,
    PRIMARY KEY(("product_id")))
WITH CUSTOM_PROPERTIES = {
    'capacity_mode':{
        'throughput_mode':'PAY_PER_REQUEST'
    },
    'point_in_time_recovery':{
        'status':'enabled'
    },
    'encryption_specification':{
        'encryption_type':'AWS_OWNED_KMS_KEY'
    }
}

You should see your new table in the list of available tables.

Perform select, insert, and update operations on frozen collections

In this section, we demonstrate how to perform select, insert, and update operations on frozen collections.

SET

A set consists of a group of elements with unique values. Duplicate values are not allowed in a set and only one copy of a value is stored. The values in a set are stored unordered, but the elements are returned in sorted order when queried. Consider a use case where you want to track the unique tags associated with each product.

Insert and select data with the following code:

INSERT INTO frozen_example.product_tags (product_id, tags)
VALUES (uuid(), {'electronics', 'home_appliance', 'home_appliance'});
 
SELECT * FROM frozen_example.product_tags;

Update the set by adding a new element:

UPDATE frozen_example.product_tags
SET tags = {'electronics', 'home_appliance', 'energy_efficient'}
WHERE product_id = e8b93759-3960-4fc4-9540-6fd3d0b783b4;

SELECT * FROM frozen_example.product_tags;

Update the set by adding a duplicate product tag:

UPDATE frozen_example.product_tags
SET tags = {'electronics', 'home_appliance', 'energy_efficient', 'energy_efficient'}
WHERE product_id = e8b93759-3960-4fc4-9540-6fd3d0b783b4;

SELECT * FROM frozen_example.product_tags WHERE product_id= e8b93759-3960-4fc4-9540-6fd3d0b783b4;

The result shows that only distinct values are stored and duplicate values are ignored. Also, results are displayed in sorted order irrespective of how the data was inserted or updated.

Now try to modify part of the frozen collection:

UPDATE frozen_example.product_tags SET tags = tags + {'new_tag'} WHERE product_id = e8b93759-3960-4fc4-9540-6fd3d0b783b4;

As shown in the following screenshot, you can’t modify a part of a frozen collection. You get an error when trying to modify part of a frozen value.

LIST

A LIST similar to a SET. However, unlike a SET, the values stored in a LIST don’t need to be unique and can be duplicated. A LIST stores the elements in the order they were inserted and when you query the list, you get the results in the same order. Imagine you want to maintain a list of product reviews for each product in your catalog.

We use the following schema:

CREATE TABLE frozen_example.product_reviews (
    product_id UUID PRIMARY KEY,
    reviews FROZEN<LIST<TEXT>>
);

Insert and select with the following code:

INSERT INTO frozen_example.product_reviews (product_id, reviews) 
VALUES (uuid(), ['Great product!', 'Could be better.']);

SELECT * FROM frozen_example.product_reviews;

The preceding screenshots display the elements in the order that they were inserted.

Update and select with the following code:

UPDATE frozen_example.product_reviews 
SET reviews = ['Great product!', 'Could be better.', 'Worth every penny!'] 
WHERE product_id = 5b3f981d-c3ee-420b-8fbd-4f253f08c56a;

SELECT * FROM frozen_example.product_reviews WHERE product_id = 5b3f981d-c3ee-420b-8fbd-4f253f08c56a;

Now try to modify part of the frozen list:

UPDATE frozen_example.product_reviews SET reviews[2] = 'New review!' WHERE product_id = 5b3f981d-c3ee-420b-8fbd-4f253f08c56a;

Just like when using a SET, you get a similar error when you try to update a frozen list.

MAP

A map relates one item to another with a key-value pair. Keys in a map must be unique, and duplicates can’t be stored. Both the key and the value have a data type. For this example, imagine tracking product metadata where each key-value pair represents a property of the product.

We use the following schema:

CREATE TABLE frozen_example.product_metadata (
    product_id UUID PRIMARY KEY,
    metadata FROZEN<MAP<TEXT, TEXT>>
);

Insert and select with the following code:

INSERT INTO frozen_example.product_metadata (product_id, metadata) 
VALUES (uuid(), {'color': 'red', 'warranty': '2 years', 'brand': 'XYZ'});

SELECT * FROM frozen_example.product_metadata;

Update and select with the following code:

UPDATE frozen_example.product_metadata 
SET metadata = {'color': 'blue', 'warranty': '2 years', 'brand': 'XYZ', 'weight': '5kg', 'material': 'steel'} 
WHERE product_id = 4ae8dcc1-5717-4d12-abb4-080b555dff58;

SELECT * FROM frozen_example.product_metadata WHERE product_id=4ae8dcc1-5717-4d12-abb4-080b555dff58;

Now try to modify part of the frozen map:

UPDATE frozen_example.product_metadata SET metadata['material'] = 'aluminium' WHERE product_id = 4ae8dcc1-5717-4d12-abb4-080b555dff58;

Again, we receive an error.

Default quota for maximum nesting depth of frozen collections

In Amazon Keyspaces, collections can have up to five levels of nesting by default. To increase the levels of nesting, you can contact AWS Support. In this section, we share examples to demonstrate how you can reach the maximum nesting depth. We create two tables, one with five levels of nested collections and another with six levels. We also share the error you encounter when you exceed the quota for the maximum nesting depth for collections.

Create a table with five levels of nested collections

Create a table with five levels of nesting in a collection by running the following query in the CQL editor:

CREATE TABLE "frozen_example"."product_metadata_v5"(
	"product_id" UUID,
	"metadata" FROZEN<MAP<TEXT, FROZEN<MAP<TEXT, FROZEN<MAP<TEXT, FROZEN<MAP<TEXT, FROZEN<MAP<TEXT, TEXT>>>>>>>>>>,
	PRIMARY KEY(("product_id"), "metadata"))
WITH CUSTOM_PROPERTIES = {
	'capacity_mode':{
		'throughput_mode':'PAY_PER_REQUEST'
	},
	'point_in_time_recovery':{
		'status':'enabled'
	},
	'encryption_specification':{
		'encryption_type':'AWS_OWNED_KMS_KEY'
	}
}
AND CLUSTERING ORDER BY("metadata" ASC)

You can also create this table using the Amazon Keyspaces console. The console provides a more intuitive way to define and visualize nested collections. The following screenshot illustrates the experience to define the schema of our example table.

In above screenshot, when you reach the quota for the maximum nesting depth, you will see a message on the console indicating that you can’t add anymore nested collections.

After you create the table, you can view the schema by choosing Tables in the Amazon Keyspaces console navigation pane and then choosing your table name.

To insert data into the newly created table with five levels of nesting, run the following query:

INSERT INTO frozen_example.product_metadata_v5 (product_id, metadata)
VALUES (
    uuid(),
    {
        'details': {
            'color': {
                'shade': {
                    'intensity': {
                        'type1': 'red_light',
                        'type2': 'red_dark'
                    }
                }
            }
        }
    }
);

To view the data in the table, run the following query:

SELECT * FROM frozen_example.product_metadata_v5;

Create a table with six levels of nested collections

The following table creation with six nested frozen collections will fail due to exceeding the quota. Contact AWS support if you want to increase this quota.

CREATE TABLE frozen_example.product_metadata_v6 (
product_id UUID PRIMARY KEY,
metadata FROZEN<MAP<TEXT, MAP<TEXT, MAP<TEXT, MAP<TEXT, MAP<TEXT, MAP<TEXT, TEXT>>>>>>>
);

Summary

In this post, we introduced support for frozen collections in Amazon Keyspaces. We discussed various use cases for frozen collections and how to use the three different types of collections: MAP, LIST, and SET. We outlined common errors that occur when you try to partially update a frozen collection, and errors that occur when you reach the quota for nested frozen collections in Amazon Keyspaces. To learn more, refer to Cassandra Query Language (CQL) elements in Amazon Keyspaces.

Do you have follow-up questions or feedback? Leave a comment. We’d love to hear your thoughts and suggestions.

About the Authors

Naveen Kantamneni is a Senior Specialist Solutions Architect based in Phoenix and leads the field for Amazon Keyspaces. Naveen serves as a trusted advisor to a diverse client base, streamlining their cloud journey and optimizing AWS services for mission critical projects. Naveen possesses over a decade and half of extensive database experience, with a strong focus on NoSQL technologies for the past many years.

Gaurav Sharma is a Senior Product Manager based in San Jose for Amazon Keyspaces. Gaurav is passionate about databases, machine learning, and distributed systems. He spends his time working with customers to understand their needs to build delightful products. Gaurav has over a decade of experience as a product manager and an engineer.