CREATE TYPE

Creates a custom data type in the keyspace that contains one or more fields of related information, such as address (street, city, state, and postal code).

The scope of a user-defined type (UDT) is keyspace-wide.

UDTs cannot contain counter fields.

See also: DROP TYPE

Syntax

user_defined_type::= udt_name udt_name::= [ keyspace_name '.' ] identifier

drop_type_statement::= CREATE TYPE [ IF NOT EXISTS ] [keyspace_name].type_name '(' field_name cql_datatype [ ',' field_name cql_datatype ]* ')' ';'

CREATE TYPE [ IF NOT EXISTS ] [<keyspace_name>].<type_name>
  (<field_name> <cql_datatype> [ , <field_name> <cql_datatype> ... ]) ;

Syntax legend

Legend
Syntax conventions	Description
UPPERCASE	Literal keyword.
Lowercase	Not literal.
`< >`	Variable value. Replace with a user-defined value.
`[]`	Optional. Square brackets (`[]`) surround optional command arguments. Do not type the square brackets.
`( )`	Group. Parentheses ( `( )` ) identify a group to choose from. Do not type the parentheses.
`\|`	Or. A vertical bar (`\|`) separates alternative elements. Type any one of the elements. Do not type the vertical bar.
`...`	Repeatable. An ellipsis ( `...` ) indicates that you can repeat the syntax element as often as required.
`'<Literal string>'`	Single quotation (`'`) marks must surround literal strings in CQL statements. Use single quotation marks to preserve upper case.
`{ <key> : <value> }`	Map collection. Braces (`{ }`) enclose map collections or key value pairs. A colon separates the key and the value.
`<datatype2`	Set, list, map, or tuple. Angle brackets ( `< >` ) enclose data types in a set, list, map, or tuple. Separate the data types with a comma.
`<cql_statement>;`	End CQL statement. A semicolon (`;`) terminates all CQL statements.
`[--]`	Separate the command line options from the command arguments with two hyphens ( `--` ). This syntax is useful when arguments might be mistaken for command line options.
`' <<schema\> ... </schema\>> '`	Search CQL only: Single quotation marks (`'`) surround an entire XML schema declaration.
`@<xml_entity>='<xml_entity_type>'`	Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.

Parameters

Parameter Description Default

Parameter	Description	Default
`keyspace_name`	Optional. Name of the keyspace that contains the table to index.	If no name is specified, the current keyspace is used.
`type_name`	Unique name for the type. CQL types are reserved for a list. See type names.
`field_name`	Define fields that are in the UDT in a comma-separated list with `cql_datatype`.
`cql_datatype`	Valid CQL data type.

keyspace_name

Optional. Name of the keyspace that contains the table to index.

If no name is specified, the current keyspace is used.

type_name

Unique name for the type. CQL types are reserved for a list. See type names.

field_name

Define fields that are in the UDT in a comma-separated list with cql_datatype.

cql_datatype

Valid CQL data type.

Once created, UDTs can be used either in a frozen or non-frozen state. In a frozen state, the UDT is stored as a single value, and cannot be altered or updated except as a whole. In a non-frozen state, the UDT is stored as a collection of fields, and can be updated individually.

Examples

Simple example

This example creates a user-defined type cycling.basic_info that consists of personal data about an individual cyclist.

CREATE TYPE IF NOT EXISTS cycling.basic_info ( 
  birthday timestamp, 
  nationality text, 
  height text,
  weight text
);
DESCRIBE TYPE cycling.basic_info;

After defining the UDT, you can create a table that has columns with the UDT. CQL collection columns and other columns support the use of user-defined types, as shown in Inserting UDTs.

Example with TTL

This example creates a user-defined type (UDT) cycling.basic_info_withTTL that consists of personal data about an individual cyclist, which includes the next_race column that will be set with a timestamp and time-to-live (TTL).

CREATE TYPE IF NOT EXISTS cycling.basic_info_expire (
  birthday timestamp,
  nationality text,
  height text,
  weight text,
  next_race text
);
DESCRIBE TYPE cycling.basic_info_expire;

To insert an entire row of data into a table using a timestamp and TTL, specify the values with an INSERT command:

INSERT INTO cycling.basic_info_TTL_expire (
  id, lastname, basics
) VALUES (
  e7ae5cf3-d358-4d99-b900-85902fda9bb0,
  'FRAME',
  {
    birthday : '1993-06-18',
    nationality : 'New Zealand',
    weight : '175',
    height : '72',
    next_race : 'Amgen Tour of California'
  }
)
USING TIMESTAMP 100 AND TTL 10000;

To insert a single UDT value with a TTL, use a UPDATE command:

UPDATE cycling.basic_info_TTL_expire USING TTL 100 
  SET basics =   {
    birthday : '1993-06-18',
    nationality : 'New Zealand',
    weight : '175',
    height : '72',
    next_race : 'Tour de France'
  }
WHERE id = e7ae5cf3-d358-4d99-b900-85902fda9bb0;

To check the write time and TTL values of a UDT use the WRITETIME and TTL functions in a SELECT command:

SELECT WRITETIME(basics), TTL(basics) FROM cycling.basic_info_TTL_expire 
WHERE id = e7ae5cf3-d358-4d99-b900-85902fda9bb0;

Results

WARNING: cqlsh was built against 5.0-beta1, but this server is 5.0.  All features may not work!

 writetime(basics) | ttl(basics)
-------------------+-------------
  1718931843099899 |          99

(1 rows)

It is important to note that you cannot use selection function writeTime on non-frozen UDT basics. This is because the UDT is not frozen and the write time is not stored with the UDT.

A string with a single quote in a UDT text field is returned with two quotes in queries and COPY commands. For example, if you store the string Single ' quote in a UDT text field, the string is returned as Single '' Quote.

CREATE TYPE

Syntax

Parameters

Usage notes

Examples

Simple example

Example with TTL

Was this helpful?

Give Feedback