Core driver¶

Contact points¶

If you don’t specify any contact point, the driver defaults to 127.0.0.1:9042:

CqlSession session = CqlSession.builder().build();

This is fine for a quick start on a developer workstation, but you’ll quickly want to provide specific addresses. There are two ways to do this:

• via SessionBuilder.addContactPoint() or SessionBuilder.addContactPoints();

• in the configuration via the basic.contact-points option.

As soon as there are explicit contact points, you also need to provide the name of the local datacenter. All contact points must belong to it (as reported in their system tables: system.local.data_center and system.peers.data_center). Again this can be specified either:

• via SessionBuilder.withLocalDatacenter();

• in the configuration via the basic.load-balancing-policy.local-datacenter option.

Here is a full programmatic example:

CqlSession session = CqlSession.builder()
    .addContactPoint(new InetSocketAddress("1.2.3.4", 9042))
    .addContactPoint(new InetSocketAddress("5.6.7.8", 9042))
    .withLocalDatacenter("datacenter1")
    .build();

And a full configuration example:

// Add `application.conf` to your classpath with the following contents:
datastax-java-driver {
  basic {
    contact-points = [ "1.2.3.4:9042", "5.6.7.8:9042" ]
    load-balancing-policy.local-datacenter = datacenter1
  }
}

For more details about the local datacenter, refer to the load balancing policy section.

Keyspace¶

By default, a session isn’t tied to any specific keyspace. You’ll need to prefix table names in your queries:

session.execute("SELECT * FROM my_keyspace.my_table WHERE id = 1");

You can also specify a keyspace at construction time, either through the configuration:

datastax-java-driver {
  basic.session-keyspace = my_keyspace
}

Or with the builder:

CqlSession session = CqlSession.builder()
  .withKeyspace(CqlIdentifier.fromCql("my_keyspace"))
  .build();

That keyspace will be used as the default when table names are not qualified:

session.execute("SELECT * FROM my_table WHERE id = 1");
session.execute("SELECT * FROM other_keyspace.other_table WHERE id = 1");

You might be tempted to open a separate session for each keyspace used in your application; however, connection pools are created at the session level, so each new session will consume additional system resources:

// Anti-pattern: creating two sessions doubles the number of TCP connections opened by the driver
CqlSession session1 = CqlSession.builder().withKeyspace(CqlIdentifier.fromCql("ks1")).build();
CqlSession session2 = CqlSession.builder().withKeyspace(CqlIdentifier.fromCql("ks2")).build();

If you issue a USE statement, it will change the default keyspace on that session:

CqlSession session = CqlSession.builder().build();
// No default keyspace set, need to prefix:
session.execute("SELECT * FROM my_keyspace.my_table WHERE id = 1");

session.execute("USE my_keyspace");
// Now the keyspace is set, unqualified query works:
session.execute("SELECT * FROM my_table WHERE id = 1");

Be very careful though: switching the keyspace at runtime is inherently thread-unsafe, so if the session is shared by multiple threads (and is usually is), it could easily cause unexpected query failures.

Finally, if you’re connecting to Cassandra 4 or above, you can specify the keyspace independently for each request:

CqlSession session = CqlSession.builder().build();
session.execute(
  SimpleStatement.newInstance("SELECT * FROM my_table WHERE id = 1")
      .setKeyspace(CqlIdentifier.fromCql("my_keyspace")));

CQL to Java type mapping¶

Sometimes the driver has to infer a CQL type from a Java type (for example when handling the values of simple statements); for those that have multiple CQL equivalents, it makes the following choices:

• java.lang.String: text

• long: bigint

• java.util.UUID: uuid

In addition to these default mappings, you can register your own types with custom codecs.

Primitive types¶

For performance reasons, the driver uses primitive Java types wherever possible (boolean, int…); the CQL value NULL is encoded as the type’s default value (false, 0…), which can be ambiguous. To distinguish NULL from actual values, use isNull:

Integer age = row.isNull("age") ? null : row.getInt("age");

Collection types¶

To ensure type safety, collection getters are generic. You need to provide type parameters matching your CQL type when calling the methods:

// Assuming given_names is a list<text>:
List<String> givenNames = row.getList("given_names", String.class);

For nested collections, element types are generic and cannot be expressed as Java Class instances. Use GenericType instead:

// Assuming teams is a set<list<text>>:
GenericType<Set<List<String>>> listOfStrings = new GenericType<Set<List<String>>>() {};
Set<List<String>> teams = row.get("teams", listOfStrings);

Since generic types are anonymous inner classes, it’s recommended to store them as constants in a utility class instead of re-creating them each time.

Row metadata¶

ResultSet and Row expose an API to explore the column metadata at runtime:

for (ColumnDefinitions.Definition definition : row.getColumnDefinitions()) {
    System.out.printf("Column %s has type %s%n",
            definition.getName(),
            definition.getType());
}