Data types
Data type is declared and enforced for each column in a table.
CQL data types
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 |
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 |
Stores a date range Truncated timestamps represent the entire date span or use the range syntax to create a custom range.
Insert the custom ranges between square brackets. For example:
If you specify a date instance using a date function, like
|
||||||||||||||||
|
strings |
Encoded as these 3 signed integers of variable lengths, where the integers represent the number of:
The number of months and days are decoded as 32-bit integers. The number of nanoseconds is decoded as a 64-bit integer. Provide the duration value using one of these formats:
Restriction: The |
||||||||||||||||
|
strings |
|||||||||||||||||
|
strings |
64-bit signed integer representing the date and time since epoch (January 1 1970 at 00:00:00 GMT) in milliseconds. INSERT or UPDATE string format is ISO-8601;
the string must contain the date and optionally can include the time and time zone, |
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 |
Specialized types
Type | Constants supported | Description | ||
---|---|---|---|---|
|
blobs |
Arbitrary bytes (no validation), expressed as hexadecimal See Blob conversion functions. |
||
|
booleans |
|||
|
integers |
64-bit signed integer
Only one counter column is allowed per table.
All other columns in a counter table must be PRIMARY KEYs.
Increment and decrement the counter with an UPDATE statement using the
|
||
|
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
Type | Constants supported | Description | ||
---|---|---|---|---|
|
Contains two coordinate values for latitude and longitude. See Creating a table with a geospatial type for details on entering point information.
|
|||
|
Comma separate list of points See Creating a table with a geospatial type for details on entering linestring information.
|
|||
|
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 indexed for more versatile querying.
Collections can be frozen or non-frozen. Frozen collections are stored as a single value and are not updatable. They must be read and written as a whole. Non-frozen collections store data that can be updated independently. Non-frozen collections are the default. In addition, 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, thus, using a set over a list whenever possible is recommended.
Collections can be nested, provided the nested collection is frozen.
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. |
Use FROZEN
on a set, map, or list to serialize multiple components into a single value, frozen<<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.
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 |
Other types
Type | Constants supported | Description |
---|---|---|
|
n/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;
explicitly declare null for elements that have no value.
Because tuples are frozen by default, tuples can contain nested tuples and be nested in other data types
For example, |
|
n/a |
Customized data type that belongs to a specific keyspace.
The UDT is only available in the keyspace where it is created.
The |
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.
Type | Description |
---|---|
custom type (Deprecated supported for backward compatibility.) |
Customized type added as a sub-class to |
Java 11 type to CQL type mapping
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 |
CQL type 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 |
Related information:
-
Date, time, and timestamp format :: Describes string format used to upsert data into columns.