CQL data types

The blob type stores binary data as Binary Large Objects (BLOBs) of arbitrary bytes (no validation). Values are hexadecimal constants in the format 0xhex or 0Xhex where hex is one or more hex characters ([0-9,a-f,A-F]). For example, 0x0000cafe3.

BLOBs are suitable for small binary payloads (small images or short strings). Storing large BLOBs, such as images or videos, can lead to unbalanced partitions and degraded performance. Therefore, the practical limit and recommended size for BLOBs is less than 1 MB, despite the maximum theoretical size of 2 GB.

You can use functions to convert between native types and BLOBs:

For examples of blob functions, see Create a table column.

The boolean type represents a true or false value. Stored internally as true or false, regardless of the original form used for INSERT or UPDATE. When inserting or updating, values are case insensitive and not quoted.

When using the CQL shell COPY TO command to import or export data, you can change the format using the boolstyle option. For example, when importing survey results that have a column of yes/no responses.

The collection data types map, list, and set are used to group and store values together in one column. The elements within a collection each have a defined type that you must specify in the table definition.

Use collections to store small amounts of related data, such as phone numbers, tags, or addresses. Collections aren’t appropriate for data that is expected to grow unbounded or data models that require extracting individual values from collections. For unbounded grouping of data, use a table with one or more clustering columns. To extract individual elements, store values in separate columns or a separate table.

For more information about using collections, see Collections in CQL.

The counter type is used exclusively to store numbers that are updated by increments or decrements, such as page views, games played, or units in inventory. Counter values are 64-bit signed integers that can only be incremented or decremented.

counter columns have the following limitations:

Counter-related settings can be set in cassandra.yaml.

For examples, see Create a table column.

Date and time data types are designed for storing time series data or other timestamps.

When writing date and time values, use single quotes around string formatted values, and no quotes for integer values. For example, compare the string format purchase_date = '2017-05-12' to the integer days since epoch format purchase_date = 17298.

For more information, see Date, time, and timestamp format.

Geospatial types are useful for storing data that is geometric in nature.

Enter numeric types in plain text in the INSERT, UPDATE, and the SELECT statement WHERE clause. For example, age = 31.

static isn’t a distinct data type. It is a modifier that can be applied to a column of any type.

Static columns apply the same value to all rows in a partition. The columns is static in every partition, but each partition can have a different value that is applied to the rows in that specific partition.

The table must have clustering columns to define static columns. Only non-clustering columns can be marked static, and a static column cannot be part of the partition key.

For an example, see Create a table column.

Wrap strings in single quotes or double dollar signs ($$) in INSERT, UPDATE, and the SELECT statement WHERE clause.

For values that contain single quotes, `, or reserved characters, you must use additional escaping or change the wrapping style. For example, to insert a comment into a text field that contains a single quote and punctuation, wrap the string in ` not ':

For more information, see Escaping characters.

The tuple type can store two or more values of the same or different data types in the same column. They are similar to collections and user-defined types (UDTs), but tuples are less strict than collections, and they don’t require defining a custom type at the keyspace level. However, DataStax recommends collections and UDTs over tuples due to the following limitations:

If you choose to use tuples, limit their use to simple groupings. When the grouping becomes more complex, consider whether a collection would be more appropriate.

Tuples are fixed-length sets that can accommodate up to 32,768 fields, but a best practice is to use no more than five fields. Additionally, tuples can contain nested tuples, and they can be nested in other data types. For example, both of the following are valid: tuple<int,tuple<text,text>,boolean> and set<tuple<text,inet>>.

For examples, see Create a table column.

Use uuid and timeuuid types to represent unique identifiers. They are often used to uniquely identify rows and ensure that each row has a distinct value. For more information, see UUID and timeuuid.

User-defined types (UDTs) are custom types that are similar to map collections. They must be defined at the keyspace level before being used in a table definition.

Use UDTs judiciously to avoid performance issues and suboptimal data models. For more information, see User-defined type (UDT) overview.

Although vector data isn’t exclusively used for vector search, the vector type is required to perform vector search on a column with CQL.

The vector type stores multiple values in a single column as an array of float32 values. Vector arrays are limited to a maximum dimension of approximately 8,000 (2¹³) items.

The following types are supported for backward compatibility only:

CQL data types have strict requirements for conversion compatibility.

Some conversions are prevented on clustering columns. Clustering columns have stricter requirements because they mandate the order in which data is written to disk.