Create a user-defined type (UDT) in Amazon Keyspaces - Amazon Keyspaces (for Apache Cassandra)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Create a user-defined type (UDT) in Amazon Keyspaces

To create a UDT in a single-Region keyspace, you can use the CREATE TYPE statement in CQL, the create-type command with the Amazon CLI, or the console.

UDT names must contain 48 characters or less, must begin with an alphabetic character, and can only contain alpha-numeric characters and underscores. Amazon Keyspaces converts upper case characters automatically into lower case characters.

Alternatively, you can declare a UDT name in double quotes. When declaring a UDT name inside double quotes, Amazon Keyspaces preserves upper casing and allows special characters.

You can also use double quotes as part of the name when you create the UDT, but you must escape each double quote character with an additional double quote character.

The following table shows examples of allowed UDT names. The first columns shows how to enter the name when you create the type, the second column shows how Amazon Keyspaces formats the name internally. Amazon Keyspaces expects the formatted name for operations like GetType.

Entered name Formatted name Note
MY_UDT my_udt Without double-quotes, Amazon Keyspaces converts all upper-case characters to lower-case.
"MY_UDT" MY_UDT With double-quotes, Amazon Keyspaces respects the upper-case characters, and removes the double-quotes from the formatted name.
"1234" 1234 With double-quotes, the name can begin with a number, and Amazon Keyspaces removes the double-quotes from the formatted name.
"Special_Ch@r@cters<>!!" Special_Ch@r@cters<>!! With double-quotes, the name can contain special characters, and Amazon Keyspaces removes the double-quotes from the formatted name.
"nested""""""quotes" nested"""quotes Amazon Keyspaces removes the outer double-quotes and the escape double-quotes from the formatted name.
Console
Create a user-defined type (UDT) with the Amazon Keyspaces console

  1. Sign in to the Amazon Web Services Management Console, and open the Amazon Keyspaces console at https://console.amazonaws.cn/keyspaces/home.

  2. In the navigation pane, choose Keyspaces, and then choose a keyspace from the list.

  3. Choose the UDTs tab.

  4. Choose Create UDT

  5. Under UDT details, enter the name for the UDT. Under UDT fields you define the schema of the UDT.

  6. To finish, choose Create UDT.

Cassandra Query Language (CQL)
Create a user-defined type (UDT) with CQL

In this example we create a new version of the book awards table used in Create a table in Amazon Keyspaces. In this table, we store all awards an author receives for a given book. We create two UDTs that are nested and contain information about the book that received an award.

  1. Create a keyspace with the name catalog. Note that UDTs are not supported in multi-Region keyspaces.

    CREATE KEYSPACE catalog WITH REPLICATION = {'class': 'SingleRegionStrategy'};

  2. Create the first type. This type stores BISAC codes, which are used to define the genre of books. A BISAC code consists out of an alpha-numeric code and up to four subject matter areas.

    CREATE TYPE catalog.bisac (
    bisac_code text,
    subject1 text,
    subject2 text,
    subject3 text,
    subject4 text
);

  3. Create a second type for book awards that uses the first UDT. The nested UDT has to be frozen.

    CREATE TYPE catalog.book (
    award_title text,
    book_title text,
    publication_date date,
    page_count int,
    ISBN text,
    genre FROZEN <bisac> 
);

  4. Create a table with a column for the author's name and uses a list type for the book awards. Note that the UDT used in the list has to be frozen.

    CREATE TABLE catalog.authors (
    author_name text PRIMARY KEY,
    awards list <FROZEN <book>>
);

  5. In this step we insert one row of data into the new table.

    CONSISTENCY LOCAL_QUORUM;
    INSERT INTO catalog.authors (author_name, awards) VALUES (
'John Stiles' , 
[{
      award_title: 'Wolf',
      book_title: 'Yesterday',
      publication_date: '2020-10-10',
      page_count: 345,
      ISBN: '026204630X',
      genre: { bisac_code:'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}
      },
      {award_title: 'Richard Roe',
      book_title: 'Who ate the cake?',
      publication_date: '2019-05-13',
      page_count: 193,
      ISBN: '9780262046305',
      genre: { bisac_code:'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}
      }]
);

  6. In the last step we read the data from the table.

    SELECT * FROM catalog.authors;

    The output of the command should look like this.

     author_name | awards
-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 John Stiles | [{award_title: 'Wolf', book_title: 'Yesterday', publication_date: 2020-10-10, page_count: 345, isbn: '026204630X', genre: {bisac_code: 'FIC014090', subject1: 'FICTION', subject2: 'Historical', subject3: '20th Century', subject4: 'Post-World War II'}}, {award_title: 'Richard Roe', book_title: 'Who ate the cake?', publication_date: 2019-05-13, page_count: 193, isbn: '9780262046305', genre: {bisac_code: 'FIC022130', subject1: 'FICTION', subject2: 'Mystery & Detective', subject3: 'Cozy', subject4: 'Culinary'}}]

(1 rows)

    For more information about CQL syntax, see CREATE TYPE.

CLI
Create a user-defined type (UDT) with the Amazon CLI

  1. To create a type you can use the following syntax.

    aws keyspaces create-type
--keyspace-name 'my_keyspace'
--type-name 'my_udt'
--field-definitions
    '[
        {"name" : "field1", "type" : "int"},
        {"name" : "field2", "type" : "text"}
    ]'

  2. The output of that command looks similar to this example. Note that typeName returns the formatted name of the UDT.

    {
    "keyspaceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/my_keyspace/",
    "typeName": "my_udt"
}