Binding Parameters

The ‘?’ marker is used to denote the bind variables in a query string. This can be used for both regular and prepared parameterized queries. In addition to adding the bind marker to your query string your application must also provide the number of bind variables to cass_statement_new() when constructing a new statement. If a query doesn’t require any bind variables then 0 can be used. cass_statement_bind_*() functions are then used to bind values to the statement’s variables. Bind variables can be bound by the marker’s index or by name and must be supplied for all bound variables.

/* Create a statement with a single parameter */
CassStatement* statement = cass_statement_new("SELECT * FROM table1 WHERE column1 = ?", 1);

cass_statement_bind_string(statement, 0, "abc");

/* Execute statement */

cass_statement_free(statement);

Variables can only be bound by name for prepared statements. This limitation exists because query metadata provided by Cassandra is required to map the variable name to the variable’s marker index.

/* Prepare statment */

/* The prepared query allocates the correct number of paramters automatically */
CassStatement* statement = cass_prepared_bind(prepared);

/* The parameter can now be bound by name */
cass_statement_bind_string_by_name(statement, "column1", "abc");

/* Execute statement */

cass_statement_free(statement);

Unbound parameters

When using Cassandra 2.2+ the driver will send a special unset value for unbound parameters (leaving the unbound column unaffected). If using older versions of Cassandra (2.1 and below) the driver will return an error for unbound parameters.

Constructing Collections

Collections are supported using CassCollection objects; supporting list, map and set Cassandra types. The code below shows how to construct a list collection; however, a set can be constructed in a very similar way. The only difference is the type CASS_COLLECTION_TYPE_SET is used to create the collection instead of CASS_COLLECTION_TYPE_LIST.

Important: Values appended to the collection can be freed immediately afterward because the values are copied.

CassStatement* statement = cass_statement_new(query, 1);

CassCollection* list = cass_collection_new(CASS_COLLECTION_TYPE_LIST, 3);

cass_collection_append_string(list, "123");
cass_collection_append_string(list, "456");
cass_collection_append_string(list, "789");

cass_statement_bind_collection(statement, 0, list);

/* The colleciton can be freed after binding */
cass_collection_free(list);

Maps are built similarly, but the key and value need to be interleaved as they are appended to the collection.

CassStatement* statement = cass_statement_new(query, 1);

CassCollection* map = cass_collection_new(CASS_COLLECTION_TYPE_MAP, 2);

/* map["abc"] = 123 */
cass_collection_append_string(map, "abc");
cass_collection_append_int32(map, 123);

/* map["def"] = 456 */
cass_collection_append_string(map, "def");
cass_collection_append_int32(map, 456);

cass_statement_bind_collection(statement, 0, map);

/* The colleciton can be freed after binding */
cass_collection_free(map);

Nested Collections

When using Cassandra 2.1+ it is possible to nest collections. A collection can be added to another collection using cass_collection_append_collection().