Map, set, and list types
The Data API supports map, set, and list types (CQL collection types).
Map
Use the map type to store a typed set of key-value pairs represented as a JSON object.
When you define a map column, you specify the data type for the keys and values.
The key type must be either text or ascii.
For an example defining a map column, see Create a table.
When written to a table, maps are internally ordered by their keys, and they are returned in that order.
The following limitations apply:
-
Maps cannot have a map, set, or list as a key or value.
-
Frozen maps created in CQL (outside the Data API) aren’t accessible through the Data API. For more information, see Support for existing tables.
Client behavior:
-
Python: Accepts plain dictionaries or
DataAPIMap. ReturnsDataAPIMap, unless you setAPIOptions.serdes_options.custom_datatypes_in_readingto false. -
TypeScript: Accepts JavaScript
Mapor plain JavaScript objects. Returns JavaScriptMap, unless you use custom serialization/deserialization logic. -
Java: Accepts and returns
java.util.Map<K, V>.
Set
Use the set type to store a typed collection of unique values represented as a JSON array.
When you define a set column, you specify the data type for the values.
For an example defining a set column, see Create a table.
When written to a table, sets are ordered by their values.
The following limitations apply:
-
Frozen sets created in CQL (outside the Data API) aren’t accessible through the Data API. For more information, see Support for existing tables.
Client behavior:
-
Python: Accepts Python sets or
DataAPISet. ReturnsDataAPISet, unless you setAPIOptions.serdes_options.custom_datatypes_in_readingto false. -
TypeScript: Accepts JavaScript
Setor plain arrays. Returns JavaScriptSet, unless you use custom serialization/deserialization logic. -
Java: Accepts and returns
java.util.Set<T>.
List
Use the list type to store a typed collection of ordered, non-unique values represented as a JSON array.
When you define a list column, you specify the data type for the values.
When written to a table, lists elements are ordered by their position in the list.
The following limitations apply:
-
Frozen lists created in CQL (outside the Data API) aren’t accessible through the Data API. For more information, see Support for existing tables.
Client behavior:
-
Python: Accepts and returns plain arrays.
-
TypeScript: Accepts and returns plain arrays.
-
Java: Accepts and returns
java.util.List<T>.
