com.datastax.oss.driver.api.core

Interface CqlSession

All Superinterfaces:

AsyncAutoCloseable, AutoCloseable, Session

public interface CqlSession
extends Session

A specialized session with convenience methods to execute CQL statements.

Field Summary

Fields inherited from interface com.datastax.oss.driver.api.core.session.Session

OSS_DRIVER_COORDINATES

Method Summary

Modifier and Type	Method and Description
static CqlSessionBuilder	builder() Returns a builder to create a new instance.
default ResultSet	execute(Statement<?> statement) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default ResultSet	execute(String query) Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).
default CompletionStage<AsyncResultSet>	executeAsync(Statement<?> statement) Executes a CQL statement asynchronously (the call returns as soon as the statement was sent, generally before the result is available).
default CompletionStage<AsyncResultSet>	executeAsync(String query) Executes a CQL statement asynchronously (the call returns as soon as the statement was sent, generally before the result is available).
default PreparedStatement	prepare(PrepareRequest request) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).
default PreparedStatement	prepare(SimpleStatement statement) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).
default PreparedStatement	prepare(String query) Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).
default CompletionStage<PreparedStatement>	prepareAsync(PrepareRequest request) Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).
default CompletionStage<PreparedStatement>	prepareAsync(SimpleStatement statement) Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).
default CompletionStage<PreparedStatement>	prepareAsync(String query) Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).

Methods inherited from interface com.datastax.oss.driver.api.core.session.Session

checkSchemaAgreement, checkSchemaAgreementAsync, execute, getContext, getKeyspace, getMetadata, getMetrics, getName, isSchemaMetadataEnabled, refreshSchema, refreshSchemaAsync, setSchemaMetadataEnabled

Methods inherited from interface com.datastax.oss.driver.api.core.AsyncAutoCloseable

close, closeAsync, closeFuture, forceCloseAsync, isClosed

Method Detail

builder

@NonNull
static CqlSessionBuilder builder()

Returns a builder to create a new instance.

Note that this builder is mutable and not thread-safe.

execute

@NonNull
default ResultSet execute(@NonNull
                                   Statement<?> statement)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

execute

@NonNull
default ResultSet execute(@NonNull
                                   String query)

Executes a CQL statement synchronously (the calling thread blocks until the result becomes available).

executeAsync

@NonNull
default CompletionStage<AsyncResultSet> executeAsync(@NonNull
                                                              Statement<?> statement)

Executes a CQL statement asynchronously (the call returns as soon as the statement was sent, generally before the result is available).

executeAsync

@NonNull
default CompletionStage<AsyncResultSet> executeAsync(@NonNull
                                                              String query)

Executes a CQL statement asynchronously (the call returns as soon as the statement was sent, generally before the result is available).

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           SimpleStatement statement)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

Note that the bound statements created from the resulting prepared statement will inherit some of the attributes of the provided simple statement. That is, given:

 SimpleStatement simpleStatement = SimpleStatement.newInstance("...");
 PreparedStatement preparedStatement = session.prepare(simpleStatement);
 BoundStatement boundStatement = preparedStatement.bind();
 

Then:

• the following methods return the same value as their counterpart on simpleStatement:
  • boundStatement.getExecutionProfileName()
  • boundStatement.getExecutionProfile()
  • boundStatement.getPagingState()
  • boundStatement.getRoutingKey()
  • boundStatement.getRoutingToken()
  • boundStatement.getCustomPayload()
  • boundStatement.isIdempotent()
  • boundStatement.getTimeout()
  • boundStatement.getPagingState()
  • boundStatement.getPageSize()
  • boundStatement.getConsistencyLevel()
  • boundStatement.getSerialConsistencyLevel()
  • boundStatement.isTracing()
• boundStatement.getRoutingKeyspace() is set from either simpleStatement.getKeyspace() (if it's not null), or simpleStatement.getRoutingKeyspace();
• on the other hand, the following attributes are not propagated:
  • boundStatement.getQueryTimestamp() will be set to Long.MIN_VALUE, meaning that the value will be assigned by the session's timestamp generator.
  • boundStatement.getNode() will always be null.

If you want to customize this behavior, you can write your own implementation of PrepareRequest and pass it to prepare(PrepareRequest).

The result of this method is cached: if you call it twice with the same SimpleStatement, you will get the same PreparedStatement instance. We still recommend keeping a reference to it (for example by caching it as a field in a DAO); if that's not possible (e.g. if query strings are generated dynamically), it's OK to call this method every time: there will just be a small performance overhead to check the internal cache. Note that caching is based on:

• the query string exactly as you provided it: the driver does not perform any kind of trimming or sanitizing.
• all other execution parameters: for example, preparing two statements with identical query strings but different consistency levels will yield distinct prepared statements.

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           String query)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

prepare

@NonNull
default PreparedStatement prepare(@NonNull
                                           PrepareRequest request)

Prepares a CQL statement synchronously (the calling thread blocks until the statement is prepared).

This variant is exposed in case you use an ad hoc PrepareRequest implementation to customize how attributes are propagated when you prepare a SimpleStatement (see prepare(SimpleStatement) for more explanations). Otherwise, you should rarely have to deal with PrepareRequest directly.

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

prepareAsync

@NonNull
default CompletionStage<PreparedStatement> prepareAsync(@NonNull
                                                                 SimpleStatement statement)

Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).

Note that the bound statements created from the resulting prepared statement will inherit some of the attributes of query; see prepare(SimpleStatement) for more details.

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

prepareAsync

@NonNull
default CompletionStage<PreparedStatement> prepareAsync(@NonNull
                                                                 String query)

Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).

The result of this method is cached (see prepare(SimpleStatement) for more explanations).

prepareAsync

@NonNull
default CompletionStage<PreparedStatement> prepareAsync(PrepareRequest request)

Prepares a CQL statement asynchronously (the call returns as soon as the prepare query was sent, generally before the statement is prepared).

This variant is exposed in case you use an ad hoc PrepareRequest implementation to customize how attributes are propagated when you prepare a SimpleStatement (see prepare(SimpleStatement) for more explanations). Otherwise, you should rarely have to deal with PrepareRequest directly.

The result of this method is cached (see prepare(SimpleStatement) for more explanations).