CQL data types
Data type is declared and enforced for each column in a table.
String types
Wrap strings in single quotes or double dollar signs ($$) in INSERT, UPDATE, and the SELECT statement WHERE clause.
|
When using single quotes, additional escaping is required for field values that contain single quotes or reserved characters, see Escaping characters. |
For example, to insert a comment into a text field that contains a single quote and emoji:
INSERT INTO cycling.comments (
id, created_at, comment
) VALUES (
e7ae5cf3-d358-4d99-b900-85902fda9bb0,
currentTimestamp(),
$$ It's pouring rain, race should have been postponed :'( $$
);Type |
Constants supported |
Description |
|
strings |
US-ASCII characters |
|
strings |
UTF-8 encoded string |
|
strings |
UTF-8 encoded string |
Numeric types
For example, age = 31.
Integers
| Type | Constants supported | Description |
|---|---|---|
|
integers |
8-bit signed integer |
|
integers |
16-bit signed integer |
|
integers |
32-bit signed integer |
|
integers |
64-bit signed integer |
|
integers |
Arbitrary-precision integer |
Decimals
The default decimal separator is a period (.). Change the decimal separator in the driver settings or using cqlshrc decimalsep option. Internally, the decimal separator is stored as a period.
| Type | Constants supported | Description | ||
|---|---|---|---|---|
|
integers, floats |
Variable-precision decimal Supports integers and floats.
|
||
|
integers, floats |
32-bit IEEE-754 floating point |
||
|
integers, floats |
64-bit IEEE-754 floating point |
Java 11 type to CQL type mapping for number types
The Java types, from which most CQL types are derived, are obvious to Java programmers. The derivation of the following types, however, might not be obvious:
| CQL Type | Java Type |
|---|---|
decimal |
|
float |
|
double |
|
varint |
Date and time types
INSERT or UPDATE date/time values using single quotes around string format or no quotes for integers.
For example, setting a date in string format purchase_date = '2017-05-12' versus specifying it as an integer in days since epoch purchase_date = 17298.
| Type | Constants supported | Description |
|---|---|---|
|
strings |
32-bit unsigned integer representing the number of days since epoch (January 1, 1970) with no corresponding time value Insert or update values as an integer (days since epoch) or in string format |
|
strings |
Similar to the Apache Solr
If you specify a date instance using a date function, like The type name is case sensitive. Enclose the type name in single quotes when creating a table. |
|
strings |
Encoded as three signed integers of variable lengths, where the integers represent the number of months, days, and nanoseconds. Provided in one of several possible formats. For details, see Date, time, and timestamp format. |
|
strings |
Encoded 64-bit signed integers representing the number of nanoseconds since midnight with no corresponding date value. The insert/update string format is |
|
strings |
64-bit signed integer representing the date and time since epoch (January 1 1970 at 00:00:00 GMT) in milliseconds. The insert/update string format is ISO-8601;
the string must contain the date and optionally can include the time and time zone, |
For more information, see Date, time, and timestamp format.
Unique identifiers
Use uuid and timeuuid types to represent unique identifiers. Read Using unique identifier types for more information.
| Type | Constants supported | Description |
|---|---|---|
|
uuids |
128-bit universally unique identifier (UUID)
Generate with the |
|
uuids |
128-bit Version 1 UUID; unique identifier that includes a "conflict-free" timestamp.
Generate with the |
Specialized types
| Type | Constants supported | Description | ||
|---|---|---|---|---|
|
blobs |
Arbitrary bytes (no validation), expressed as hexadecimal See Blob conversion functions. |
||
|
booleans |
|||
|
integers |
64-bit signed integer.
A |
||
|
strings |
IP address string in IPv4 or IPv6 format |
||
|
any |
A column that is shared by all rows in a partition with a single value. See Create a static column. |
Geospatial types
|
Geospatial types aren’t available in open-source Cassandra. |
Geospatial type names are case sensitive. Enclose the type name in single quotes when creating a table.
| Type | Description |
|---|---|
|
Contains two coordinate values for latitude and longitude. |
|
Comma-separated list of points. |
|
Set of two linestrings. |
Collection types
Collection data types are a way to group and store data together in a column. Use collections to store small amounts of data, such as phone numbers, tags, or addresses.
Collections are not appropriate for data that is expected to grow unbounded, such as all events for a particular user. For unbounded grouping of data, use a table with one or more clustering columns.
Collections can be frozen or non-frozen:
-
Frozen: Stored as a single value, cannot be updated piecemeal. They must be read and written as a whole.
To nest collections, the nested collection must be frozen.
Use
FROZENon a set, map, or list to serialize multiple components into a single value, such asfrozen<<collection_definition>>. Non-frozen types allow updates to individual fields, but values in a frozen collection are treated like blobs: Any upsert overwrites the entire value. -
Non-frozen: Store data that can be updated independently. Non-frozen is the default behavior if unspecified when defining the collection.
Some non-frozen list collection operations require a read-before-write, such as inserting an element at a specific index. Sets and maps never incur a read-before-write internally on insertion; therefore, using a set over a list whenever possible is recommended.
In a non-frozen collection, a tombstone is created for an insert and a non-incremental update in the collection. An incremental update adds a value to an existing value in the collection. The inserts and non-incremental updates for a non-frozen collection can cause large numbers of tombstones.
| Type | Constants supported | Description | ||
|---|---|---|---|---|
|
n/a |
Comma separated list of unique values sorted by position starting at zero. Supports appending and prepending elements in INSERT and UPDATE statements using the + and - operators if non-frozen. |
||
|
n/a |
Comma separated list of non-unique values of the same data type,
Also list operations are not idempotent by nature and can cause timeout issues in the case of retries. |
||
|
n/a |
Tuple type
tuple is a fixed length set of elements of different types.
A tuple is always frozen without the need of the frozen keyword.
The entire field is overwritten when using INSERT and UPDATE.
Therefore, the expressions must provide a value for each element, and you must explicitly declare null for elements that have no value.
Because tuples are frozen by default, tuples can contain nested tuples, and they can be nested in other data types.
For example, tuple<int,tuple<text,text>,boolean> and set<tuple<text,inet>> are both valid data type declarations.
User-defined type (UDT)
UDT is a customized data type that belongs to a specific keyspace.
The UDT is only available in the keyspace where it is created. You must define the UDT itself on the keyspace before using it in a table definition.
The system_schema.types table contains a list of all UDTs with the keyspace_name, type_name, field_names, and field_types.
Vector type
CQL supports storing multiple values in a single column in a vector array with a limited data type for the array values. Use vectors for storing AI embeddings, with values of float32.
Vectors are limited to a maximum dimension of 8K (2^13) items.
Deprecated types
The following types are supported for backward compatibility only:
-
custom type: Customized type added as a sub-class to
AbstractTypewhere the class name was fully qualified or relative to theorg.apache.cassandra.db.marshalpackage. Replaced by user defined type (UDT).
CQL type conversion compatibility
CQL data types have strict requirements for conversion compatibility. The following table shows the allowed alterations for data types:
| Original data type | Data type to convert to |
|---|---|
ascii, bigint, boolean, decimal, double, float, inet, int, timestamp, timeuuid, uuid, varchar, varint |
blob |
int |
varint |
text |
varchar |
timeuuid |
uuid |
varchar |
text |
Clustering columns have even stricter requirements because clustering columns mandate the order in which data is written to disk. The following table shows the allowed alterations for data types used in clustering columns:
| Original data type | Data type to convert to |
|---|---|
int |
varint |
text |
varchar |
varchar |
text |
