Michael Penick

We are pleased to announce the 2.1 beta release of the C/C++ driver for Apache Cassandra and DataStax Enterprise. This release includes a majority of client-side features required to take advantage of Apache Cassandra 2.1 and DataStax Enterprise 4.7. These features include support for user defined types, tuples, nested (frozen) collections and named parameters. The final 2.1 release will also include client-side timestamps, support for the full range of stream IDs available in CQL native protocol version 3 and retry polices.

<h2>What’s new</h2>

<h3>User defined types</h3>

User defined types (UDTs for short), introduced in Apache Cassandra 2.1, allow for creating composite data types with multiple fields in a single column. This can be useful for simplifying schema by grouping related fields into a single UDT instead of using multiple columns. More information about using UDTs can be found in this&nbsp;<a href="https://www.datastax.com/dev/blog/cql-in-2-1" title="CQL improvements in Cassandra 2.1">post</a>.

<h4>A UDT constructed from a data type definition found in schema metadata</h4>

<code>int</code> <code>rc; 
 
const</code> <code>CassSchema* schema; 
const</code> <code>CassDataType* data_type1; 
 
CassStatement* statement; 
CassUserType* user_type1; 
CassFuture* future; 
 
const</code> <code>char</code><code>* query = </code><code>"INSERT INTO keyspace1.table1 (key, value) VALUES (?, ?)"</code><code>; 
 
/* Schema and type information is usually pretty static, therefore these 
&nbsp;* objects should be retreived sporadically and cached */ 
schema = cass_session_get_schema(session); 
data_type1 = cass_schema_get_udt(schema, "keyspace1"</code><code>, </code><code>"type1"</code><code>); 
 
statement = cass_statement_new(query, 2); 
 
/* The user type is created using the data type description found in the 
&nbsp;* Cassandra schema metadata */ 
user_type1 = cass_user_type_new_from_data_type(data_type1); 
 
/* Values can be bound to a UDT by name (as well as by position) */ 
cass_user_type_set_string_by_name(user_type1, "field1"</code><code>, </code><code>"abc"</code><code>); 
cass_user_type_set_int32_by_name(user_type1, "field2"</code><code>, 123); 
 
/* Bind the parameters to the query */ 
cass_statement_bind_string(statement, 0, "key1"</code><code>); 
cass_statement_bind_user_type(statement, 1, user_type1); 
 
future = cass_session_execute(session, statement); 
 
rc = cass_future_error_code(future); 
if</code> <code>(rc != CASS_OK) { 
&nbsp; /* Handle error */ 
} 
 
/* Clean up */ 
cass_schema_free(schema); 
cass_statement_free(statement); 
cass_user_type_free(user_type1); 
cass_future_free(future);</code>

&nbsp;

A UDT constructed from a manually created data type definition&nbsp;

<code>int</code> <code>rc; 
 
CassDataType* data_type1; /* Notice: not const */ 
CassStatement* statement; 
CassUserType* user_type1; 
CassFuture* future; 
 
const</code> <code>char</code><code>* query = </code><code>"INSERT INTO keyspace1.table1 (key, value) VALUES (?, ?)"</code><code>; 
 
/* Manually create a data type that describes the UDT. 
&nbsp;* This should be created once and cached. */ 
data_type1 = cass_data_type_new(CASS_VALUE_TYPE_UDT); 
cass_data_type_add_sub_value_type_by_name(data_type1, "field1"</code><code>, CASS_VALUE_TYPE_TEXT); 
cass_data_type_add_sub_value_type_by_name(data_type1, "field2"</code><code>, CASS_VALUE_TYPE_INT); 
 
statement = cass_statement_new(query, 2); 
/* The user type is created using the data type description built previously */ 
user_type1 = cass_user_type_new_from_data_type(data_type1); 
 
/* Values can be bound to a UDT by name (as well as by position) */ 
cass_user_type_set_string_by_name(user_type1, "field1"</code><code>, </code><code>"def"</code><code>); 
cass_user_type_set_int32_by_name(user_type1, "field2"</code><code>, 456); 
 
/* Bind the parameters to the query */ 
cass_statement_bind_string(statement, 0, "key2"</code><code>); 
cass_statement_bind_user_type(statement, 1, user_type1); 
 
future = cass_session_execute(session, statement); 
 
rc = cass_future_error_code(future); 
if</code> <code>(rc != CASS_OK) { 
&nbsp;&nbsp;/* Handle error */ 
} 
 
/* Clean up */ 
cass_data_type_free(data_type1); 
cass_statement_free(statement); 
cass_user_type_free(user_type1); 
cass_future_free(future);</code>

<h4>Selecting a UDT value and iterating over its fields</h4>

<code>CassStatement* statement; 
CassFuture* future; 
const</code> <code>CassResult* result; 
 
const</code> <code>char</code><code>* query = </code><code>"SELECT value FROM keyspace1.table1"</code><code>; 
statement = cass_statement_new(query, 0); 
future = cass_session_execute(session, statement); 
 
result = cass_future_get_result(future); 
if</code> <code>(result != NULL &amp;&amp; cass_result_row_count(result) &gt; 0) { 
&nbsp;&nbsp;const</code> <code>CassRow* row = cass_result_first_row(result); 
 
&nbsp;&nbsp;/* Create an iterator to iterate over the UDT's fields */ 
&nbsp;&nbsp;CassIterator* fields_iterator = 
&nbsp;&nbsp;&nbsp;&nbsp;cass_iterator_from_user_type(cass_row_get_column_by_name(row, </code><code>"value"</code><code>)); 
 
&nbsp;&nbsp;while</code> <code>(cass_iterator_next(fields_iterator)) { 
&nbsp;&nbsp;&nbsp;&nbsp;const</code> <code>char</code><code>* field_name; 
&nbsp;&nbsp;&nbsp;&nbsp;size_t</code> <code>field_name_size; 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* Get the field's name */ 
&nbsp;&nbsp;&nbsp;&nbsp;cass_iterator_get_user_type_field_name(fields_iterator, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;field_name, &amp;field_name_size); 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* Get the field's value */ 
&nbsp;&nbsp;&nbsp;&nbsp;if</code> <code>(</code><code>strncmp</code><code>(field_name, </code><code>"field1"</code><code>, field_name_size) == 0) { 
&nbsp; &nbsp; &nbsp; const</code> <code>char</code><code>* field1_value; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t</code> <code>field1_value_size; 
&nbsp; &nbsp; &nbsp; cass_value_get_string(cass_iterator_get_user_type_field_value(fields_iterator), 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;field1_value, &amp;field1_value_size); 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Use field1's value */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf</code><code>(</code><code>"%.*s %.*s\n"</code><code>, (</code><code>int</code><code>)field_name_size, field_name, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(</code><code>int</code><code>)field1_value_size, field1_value); 
&nbsp;&nbsp;&nbsp;&nbsp;} </code><code>else</code> <code>if</code> <code>(</code><code>strncmp</code><code>(field_name, </code><code>"field2"</code><code>, field_name_size) == 0) { 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cass_int32_t field2_value; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cass_value_get_int32(cass_iterator_get_user_type_field_value(fields_iterator), 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;field2_value); 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Use field2's value */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf</code><code>(</code><code>"%.*s %d\n"</code><code>, (</code><code>int</code><code>)field_name_size, field_name, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;field2_value); 
&nbsp;&nbsp;&nbsp;&nbsp;} 
&nbsp;&nbsp;} 
 
&nbsp;&nbsp;cass_iterator_free(fields_iterator); 
} else</code> <code>{ 
&nbsp;&nbsp;/* Handle error */ 
} 
 
cass_statement_free(statement); 
cass_future_free(future);</code>

<h4>&nbsp;</h4>

<h4>UDT schema</h4>

<code>CREATE KEYSPACE keyspace1 
WITH replication = { 'class': 'SimpleStrategy', 'replication_factor': '3' }; 
 
CREATE TYPE keyspace1.type1 (field1 text, field2 int); 
 
CREATE TABLE keyspace1.table1 (key text PRIMARY KEY, value frozen&lt;type1&gt;)</code>

Tuples 
Tuples, also introduced in Apache Cassandra 2.1, are useful for creating positional, fixed length sets of multiple types. They're similar to UDTs in that they are arbitrary composite types, however; tuple fields are unnamed, therefore its fields can only be referenced by position. This also means that it is not possible to add new fields to a tuple.

<h4>Inserting a tuple value</h4>

<code>int</code> <code>rc; 
 
CassStatement* statement; 
CassTuple* tuple; 
CassFuture* future; 
 
const</code> <code>char</code><code>* query = </code><code>"INSERT INTO keyspace1.table2 (key, value) VALUES (?, ?)"</code><code>; 
 
statement = cass_statement_new(query, 2); 
 
tuple = cass_tuple_new(2); 
 
/* Values are bound to a tuple by position */ 
cass_tuple_set_string(tuple, 0, "abc"</code><code>); 
cass_tuple_set_int32(tuple, 1, 123); 
 
/* Bind the parameters to the query */ 
cass_statement_bind_string(statement, 0, "key1"</code><code>); 
cass_statement_bind_tuple(statement, 1, tuple); 
 
future = cass_session_execute(session, statement); 
 
rc = cass_future_error_code(future); 
if</code> <code>(rc != CASS_OK) { 
&nbsp;&nbsp;/* Handle error */ 
} 
 
/* Clean up */ 
cass_statement_free(statement); 
cass_tuple_free(tuple); 
cass_future_free(future);</code>

<h4>Selecting a tuple value and iterating over its fields</h4>

<code>CassStatement* statement; 
CassFuture* future; 
const</code> <code>CassResult* result; 
 
const</code> <code>char</code><code>* query = </code><code>"SELECT value FROM keyspace1.table2"</code><code>; 
 
statement = cass_statement_new(query, 0); 
future = cass_session_execute(session, statement);</code>

 
<code>result = cass_future_get_result(future); 
if</code> <code>(result != NULL &amp;&amp; cass_result_row_count(result) &gt; 0) { 
&nbsp;&nbsp;const</code> <code>CassRow* row = cass_result_first_row(result); 
 
&nbsp;&nbsp;/* Create an iterator to iterate over the tuple's fields */ 
&nbsp;&nbsp;CassIterator* tuple_iterator = 
&nbsp;&nbsp;&nbsp;&nbsp;cass_iterator_from_tuple(cass_row_get_column_by_name(row, </code><code>"value"</code><code>)); 
 
&nbsp;&nbsp;while</code> <code>(cass_iterator_next(tuple_iterator)) { 
&nbsp;&nbsp;&nbsp;&nbsp;const</code> <code>CassValue* value = cass_iterator_get_value(tuple_iterator); 
 
&nbsp;&nbsp;&nbsp;&nbsp;/* Get the tuple field's value */ 
&nbsp;&nbsp;&nbsp;&nbsp;if</code> <code>(cass_value_type(value) == CASS_VALUE_TYPE_TEXT) { 
&nbsp; &nbsp; &nbsp; const</code> <code>char</code><code>* text_value; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;size_t</code> <code>text_value_size; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cass_value_get_string(value, 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;text_value, &amp;text_value_size); 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Use value */ 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;printf</code><code>(</code><code>"%.*s\n"</code><code>, (</code><code>int</code><code>)text_value_size, text_value); 
&nbsp;&nbsp;&nbsp;&nbsp;} </code><code>else</code> <code>if</code> <code>(cass_value_type(value) == CASS_VALUE_TYPE_INT) { 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cass_int32_t int_value; 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cass_value_get_int32(value, &amp;int_value); 
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/* Use value */ 
&nbsp; &nbsp; &nbsp; printf</code><code>(</code><code>"%d\n"</code><code>, int_value); 
&nbsp;&nbsp;&nbsp;&nbsp;} 
&nbsp;&nbsp;} 
 
&nbsp;cass_iterator_free(tuple_iterator); 
} else</code> <code>{ 
&nbsp;&nbsp;/* Handle error */ 
} 
 
cass_statement_free(statement); 
cass_future_free(future);</code>

&nbsp;

<h4>Tuple schema</h4>

CREATE TABLE keyspace1.table2 (key text PRIMARY KEY, value frozen&lt;tuple&lt;text, int&gt;&gt;);

Nested collections 
With the release of Apache Cassandra 2.1 it is now possible to nest immutable (known as "frozen") collections within other collections. To support this feature the driver added functions and internal serialization logic to allow appending collections inside other collections.

<h4>A new method has been added for nesting collections</h4>

<code>/* A nested collection can be appended to another collection */ 
cass_collection_append_collection(collection, nested_collection);</code>

<h4>Collection values can now be recursively iterated</h4>

<code>/* A nested collection can be retreived from another collection */ 
const</code> <code>CassValue* nested_collection = cass_iterator_get_value(collection); 
CassIterator* nested_collection_iterator = 
cass_iterator_from_collection(nested_collection); 
 
/* Iterate over nested collection */</code>

<h3>Named parameters</h3>

It is possible to name parameters inside a query string. In previous releases only positional parameters were supported for non-prepared queries, that is, parameters denoted with "?" needed to be bound to a query in the same order as they appeared in the query string. This version of the driver allows parameters to be named using the ":&lt;name&gt;" syntax. Named parameters can also be used in conjunction with prepared queries, but are most useful for non-prepared queries where metadata for the parameters' names are not available.

<code>int</code> <code>rc; 
 
CassStatement* statement; 
CassTuple* tuple; 
CassFuture* future; 
 
/* The query string uses the form ":&amp;lt;name&amp;gt;" of parameters instead of "?" */ 
const</code> <code>char</code><code>* query = </code><code>"INSERT INTO keyspace1.table2 (key, value) VALUES (:k, :v)"</code><code>; 
 
statement = cass_statement_new(query, 2); 
 
tuple = cass_tuple_new(2); 
 
/* Values are bound to a tuple by position */ 
cass_tuple_set_string(tuple, 0, "def"</code><code>); 
cass_tuple_set_int32(tuple, 1, 456); 
 
/* Bind the parameters to the query using names */cass_statement_bind_string_by_name(statement, "k"</code><code>, </code><code>"key2"</code><code>); 
cass_statement_bind_tuple_by_name(statement, "v"</code><code>, tuple); 
 
future = cass_session_execute(session, statement); 
 
rc = cass_future_error_code(future); 
if</code> <code>(rc != CASS_OK) { 
&nbsp;&nbsp;/* Handle error */ 
} 
 
/* Clean up */ 
cass_statement_free(statement); 
cass_tuple_free(tuple); 
cass_future_free(future);</code>

<h3>This release includes a couple internal improvements:Internal improvements</h3>

<ul>
	<li>The driver now supports version 3 of the CQL native protocol allowing the driver to support new client-side features as well as supporting larger range of stream IDs. The larger range of stream IDs will allow the driver to achieve higher query throughput with less connections. The next driver release will fully capitalize on this potential increase in performance.</li>
	<li>Read buffers are now cached and reused inside a connection. This is a big performance win on Windows and has the potential to improve performance on other platforms too. More information can be found in the<a href="https://datastax-oss.atlassian.net/browse/CPP-247">JIRA issue</a>.</li>
</ul>

<h3>What's next</h3>

In the next release we plan to finish Apache Cassandra 2.1 support and address any feedback or issues introduced by this beta release. Let us know what you think of the new features and API. To provide feedback use the following:

<ul>
	<li>Mailing List:&nbsp;<a href="https://groups.google.com/a/lists.datastax.com/forum/#!forum/cpp-driver-user">https://groups.google.com/a/lists.datastax.com/forum/#!forum/cpp-driver-user</a></li>
	<li>IRC: #datastax-drivers on irc.freenode.net</li>
	<li>Review and contribute source code:&nbsp;<a href="https://github.com/datastax/cpp-driver">https://github.com/datastax/cpp-driver</a></li>
	<li>Report issues on JIRA:&nbsp;<a href="https://datastax-oss.atlassian.net/browse/CPP">https://datastax-oss.atlassian.net/browse/CPP</a></li>
</ul>

&nbsp;

DataStax C/C++ Driver: 2.1 Beta released!

Michael PenickDataStax

Discover more

Share

Share

What’s new

User defined types

A UDT constructed from a data type definition found in schema metadata

Selecting a UDT value and iterating over its fields

UDT schema

Inserting a tuple value

Selecting a tuple value and iterating over its fields

Tuple schema

A new method has been added for nesting collections

Collection values can now be recursively iterated

Named parameters

This release includes a couple internal improvements:Internal improvements

What's next

More Company

DataStax Acquires Langflow to Accelerate Generative AI Development

The Top 5 DataStax Stories from 2023

2023 Recap: Data = AI

DataStax Astra DB Nabs Three Prestigious 2023 TrustRadius “Best of” Awards, Dominates the Vector Databases Category

One-stop Data API for Production GenAI