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 also could be bound by name, where name could be inferred from query, or explicitly specified as :name
. (Until Cassandra 2.1, bind by name might be done only for prepared statements. This limitation did exist because query metadata provided by Cassandra is required to map the variable name to the variable’s marker index.)
void execute_prepared_statement(const CassPrepared* prepared) {
/* 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. Calling cass_statement_reset_parameters()
will unbind (or
resize) a statement’s 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.
const char* query = "SELECT * FROM ...";
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.
const char* query = "SELECT * FROM ...";
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()
.
Custom types
Custom types can be bound using either the cass_statement_bind_bytes[_by_name]()
or the
cass_statement_bind_custom[by_name]()
functions. The latter validates the class
name of the custom type matches the class name of the type being bound.