Keyspaces¶

Setting the Keyspace at Connection Time¶

A session can be initially connected using a supplied keyspace. This is the recommended way to set the keyspace for a session, as it prevents races between setting keyspace and requests being executed. This is particularly important in applications that use a single session object shared by multiple threads.

Performance Tip: An application should create a single session object per keyspace as a session object is designed to be created once, reused, and shared by multiple threads within the application. Even better performance can be achieved by creating a single session object per application, but then if the application interacts with multiple keyspaces, it must fully qualify the table names in its statements.

CassSession* session = cass_session_new();
CassCluster* cluster = cass_cluster_new();

/* Configure cluster */

CassFuture* connect_future
  = cass_session_connect_keyspace(session, cluster, "keyspace1");

/* Handle connect future */

cass_future_free(connect_future);

cass_session_free(session);
cass_cluster_free(cluster);

Changing Keyspaces¶

You can specify a keyspace to change to by executing a USE statement on a connection session object.

void use_keyspace(CassSession* session) {
  CassStatement* use_statement
    = cass_statement_new("USE keyspace1", 0);

  CassFuture* use_future
    = cass_session_execute(session, use_statement);

  /* Check future result... */

  cass_statement_free(use_statement);
  cass_future_free(use_future);
}

Be very careful though: if the session is shared by multiple threads, switching the keyspace at runtime could easily cause unexpected query failures.

Single Session and Multiple Keyspaces¶

It is possible to interact with multiple keyspaces using a single session object by fully qualifying the table names in your queries e.g. keyspace_name.table_name.

SELECT * FROM keyspace_name.table_name WHERE ...;
INSERT INTO keyspace_name.table_name (...) VALUES (...);

Creating Keyspaces and Tables¶

It is also possible to create keyspaces and tables by executing CQL using a session object.

CREATE KEYSPACE cpp_driver
  WITH REPLICATION = { 'class' : 'SimpleStrategy', 'replication_factor' : 1 };
CREATE TABLE cpp_driver.contributors (
  lastname text,
  firstname text,
  company text,
  website text,
  since timestamp,
  last_activity timestamp,
  PRIMARY KEY(lastname));