ScyllaDB Docs ScyllaDB Rust Driver Executing CQL statements - best practices USE keyspace

For AI agents: a documentation index is available at https://rust-driver.docs.scylladb.com/main/llms.txt. A Markdown version of this page is at https://rust-driver.docs.scylladb.com/main/statements/usekeyspace.md.

Caution

You're viewing documentation for an unstable version of ScyllaDB Rust Driver. Switch to the latest stable version.

USE keyspace¶

Using a keyspace allows to omit keyspace name in statements.

For example in cqlsh one could write:

cqlsh> SELECT * FROM my_keyspace.table;

 a     | b     |
-------+-------+
 12345 | 54321 |

(1 rows)
cqlsh> USE my_keyspace;
cqlsh:my_keyspace> SELECT * FROM table;

 a     | b     |
-------+-------+
 12345 | 54321 |

(1 rows)

Tables from other keyspaces can still easily be accessed by using their keyspace names.

cqlsh:my_keyspace> SELECT * FROM other_keyspace.other_table;

In the driver this can be achieved using Session::use_keyspace:

session
    .query_unpaged("INSERT INTO my_keyspace.tab (a) VALUES ('test1')", &[])
    .await?;

session.use_keyspace("my_keyspace", false).await?;

// Now we can omit keyspace name in the statement
session
    .query_unpaged("INSERT INTO tab (a) VALUES ('test2')", &[])
    .await?;

The first argument is the keyspace name.

The second argument states whether this name is case sensitive.

It is also possible to send raw use keyspace statement using Session::query_* instead of Session::use_keyspace such as:

session.query_unpaged("USE my_keyspace", &[]).await?;

This method has a slightly worse latency than Session::use_keyspace - there are two roundtrips needed instead of one. Therefore, Session::use_keyspace is the preferred method for setting keyspaces.

Caveats¶

When preparing statements, the driver receives an ID for the prepared statement. Rust Driver (and every other driver for that matter) assumes that this ID is immutable: if it changed during a reprepare, an error will be returned.

This assumption is not strictly true. For statements that don’t specify keyspace explicitly, like SELECT col FROM table, a current keyspace will be used, and it will be considered when calculating hash of prepared statement. This is true for both databases (ScyllaDB and Cassandra).

That means if you prepare such statement, and then change the keyspace, and it gets reprepared (which can happen at any time) it will no longer be usable. In other words, you should not prepare a statement without keyspace, and then switch the keyspace, no matter which DB you are using.

“Not usable” means that such statements execution will likely return ExecutionError::LastAttemptError(RequestAttemptError::RepreparedIdChanged { .. }), and to fix that you would need to drop the statement, and prepare it again.

For ScyllaDB there is unfortunately one more problem: current keyspace is ALWAYS considered when calculating the id, even if the statement already specifies the keyspace (like SELECT col FROM ks.table). That means the problem described above can happen even if you specify the keyspace, so the recommendation is even stricter: Do not switch keyspace after preparing any statements, or more specifically, don’t use statements that were prepared for other keyspace.

Warning

Do not use unqualified (like SELECT col FROM table) prepared statements that were prepared for a different keyspace than your session currently uses.

Warning

If you use ScyllaDB, do not use prepared statements that were prepared for a different keyspace than your session currently uses - no matter if the statements specify the keyspace explicitly or not. One way to do this is to set Session keyspace once, on creation, and never change it again.

Case sensitivity¶

In CQL a keyspace name can be case insensitive (without ") or case sensitive (with ").

If the second argument to use_keyspace is set to true this keyspace name will be wrapped in ".

It is best to avoid the problem altogether and just not create two keyspaces with the same name but different cases.

Let’s see what happens when there are two keyspaces with the same name but different cases: my_keyspace and MY_KEYSPACE:

// lowercase name without case sensitivity will use my_keyspace
session.use_keyspace("my_keyspace", false).await?;

// lowercase name with case sensitivity will use my_keyspace
session.use_keyspace("my_keyspace", true).await?;

// uppercase name without case sensitivity will use my_keyspace
session.use_keyspace("MY_KEYSPACE", false).await?;

// uppercase name with case sensitivity will use MY_KEYSPACE
session.use_keyspace("MY_KEYSPACE", true).await?;

Was this page helpful?