Cassandra identifiers, such as keyspace, table and column names, are case-insensitive by default. For example, if you create the following table:
cqlsh> CREATE TABLE test.FooBar(k int PRIMARY KEY);
Cassandra actually stores the table name as lower-case:
cqlsh> SELECT table_name FROM system_schema.tables WHERE keyspace_name = 'test'; table_name ------------ foobar
And you can use whatever case you want in your queries:
cqlsh> SELECT * FROM test.FooBar; cqlsh> SELECT * FROM test.foobar; cqlsh> SELECT * FROM test.FoObAr;
However, if you enclose an identifier in double quotes, it becomes case-sensitive:
cqlsh> CREATE TABLE test."FooBar"(k int PRIMARY KEY); cqlsh> SELECT table_name FROM system_schema.tables WHERE keyspace_name = 'test'; table_name ------------ FooBar
You now have to use the exact, quoted form in your queries:
cqlsh> SELECT * FROM test."FooBar";
If you forget to quote, or use the wrong case, you’ll get an error:
cqlsh> SELECT * FROM test.Foobar; InvalidRequest: Error from server: code=2200 [Invalid query] message="table foobar does not exist" cqlsh> SELECT * FROM test."FOOBAR"; InvalidRequest: Error from server: code=2200 [Invalid query] message="table FOOBAR does not exist"
When we deal with identifiers, we use the following definitions:
CQL form: how you would type it in a CQL query. In other words, case-sensitive if it’s quoted, case-insensitive otherwise;
internal form: how it is stored in system tables. In other words, never quoted and always in its exact case.
In previous driver versions, identifiers were represented as raw strings. The problem is that this does not capture the form; when a method processed an identifier, it always had to know where it came from and what form it was in, and possibly convert it. This led a lot of internal complexity, and recurring bugs.
To address this issue, driver 4+ uses a wrapper: CqlIdentifier. Its API methods are always explicit about the form:
CqlIdentifier caseInsensitiveId = CqlIdentifier.fromCql("FooBar"); System.out.println(caseInsensitiveId.asInternal()); // foobar System.out.println(caseInsensitiveId.asCql(/*pretty=*/ false)); // "foobar" System.out.println(caseInsensitiveId.asCql(true)); // foobar // Double-quotes need to be escaped inside Java strings CqlIdentifier caseSensitiveId = CqlIdentifier.fromCql("\"FooBar\""); System.out.println(caseSensitiveId.asInternal()); // FooBar System.out.println(caseSensitiveId.asCql(true)); // "FooBar" System.out.println(caseSensitiveId.asCql(false)); // "FooBar" CqlIdentifier caseSensitiveId2 = CqlIdentifier.fromInternal("FooBar"); assert caseSensitiveId.equals(caseSensitiveId2);
Side note: as shown above,
asCql has a pretty-printing option that omits the quotes if they are
not necessary. This looks nicer, but is slightly more expensive because it requires parsing the
The driver API uses
CqlIdentifier whenever it produces or consumes an identifier. For example:
getting the keyspace from a table’s metadata:
CqlIdentifier keyspaceId = tableMetadata.getKeyspace();
setting the keyspace when building a session:
For “consuming” methods, string overloads are also provided for convenience, for example
getters and setters of “data container” types Row, UdtValue, and BoundStatement follow
special rules described here (these methods are treated apart because they are
generally invoked very often, and therefore avoid to create
CqlIdentifier instances internally);
in other cases, the string is always assumed to be in CQL form, and converted on the fly with
As should be clear by now, case sensitivity introduces a lot of extra (and arguably unnecessary) complexity.
The Java driver team’s recommendation is:
Always use case-insensitive identifiers in your data model.
You’ll never have to create
CqlIdentifier instances in your application code, nor think about
CQL/internal forms. When you pass an identifier to the driver, use the string-based methods. When
the driver returns an identifier and you need to convert it into a string, use
If you worry about readability, use snake case (
shopping_cart), or simply stick to camel case
ShoppingCart) and ignore the fact that Cassandra lower-cases everything internally.
The only reason to use case sensitivity should be if you don’t control the data model. In that
case, either pass quoted strings to the driver, or use
CqlIdentifier instances (stored as
constants to avoid creating them over and over).