com.datastax.oss.driver.api.core.cql

Interface SimpleStatement

All Superinterfaces:

BatchableStatement<SimpleStatement>, Request, Statement<SimpleStatement>

public interface SimpleStatement
extends BatchableStatement<SimpleStatement>

A one-off CQL statement consisting of a query string with optional placeholders, and a set of values for these placeholders.

To create instances, client applications can use the newInstance factory methods on this interface for common cases, or builder(String) for more control over the parameters. They can then be passed to SyncCqlSession.execute(Statement).

Simple statements should be reserved for queries that will only be executed a few times by an application. For more frequent queries, PreparedStatement provides many advantages: it is more efficient because the server parses the query only once and caches the result; it allows the server to return metadata about the bind variables, which allows the driver to validate the values earlier, and apply certain optimizations like token-aware routing.

The default implementation returned by the driver is immutable and thread-safe. All mutating methods return a new instance. See also the static factory methods and builders in this interface.

If an application reuses the same statement more than once, it is recommended to cache it (for example in a final field).

Field Summary

Fields inherited from interface com.datastax.oss.driver.api.core.cql.Statement

ASYNC, NO_DEFAULT_TIMESTAMP, NO_NOW_IN_SECONDS, SYNC

Method Summary

Modifier and Type	Method and Description
static SimpleStatementBuilder	builder(SimpleStatement template) Returns a builder to create an instance of the default implementation, copying the fields of the given statement.
static SimpleStatementBuilder	builder(String query) Returns a builder to create an instance of the default implementation.
default int	computeSizeInBytes(DriverContext context) Calculates the approximate size in bytes that the statement will have when encoded.
Map<CqlIdentifier,Object>	getNamedValues()
List<Object>	getPositionalValues()
String	getQuery()
static SimpleStatement	newInstance(String cqlQuery) Shortcut to create an instance of the default implementation with only a CQL query (see SimpleStatementBuilder for the defaults for the other fields).
static SimpleStatement	newInstance(String cqlQuery, Map<String,Object> namedValues) Shortcut to create an instance of the default implementation with only a CQL query and named values (see SimpleStatementBuilder for the defaults for other fields).
static SimpleStatement	newInstance(String cqlQuery, Object... positionalValues) Shortcut to create an instance of the default implementation with only a CQL query and positional values (see SimpleStatementBuilder for the defaults for the other fields).
SimpleStatement	setKeyspace(CqlIdentifier newKeyspace) Sets the CQL keyspace to associate with the query.
default SimpleStatement	setKeyspace(String newKeyspaceName) Shortcut for setKeyspace(CqlIdentifier.fromCql(newKeyspaceName)).
default SimpleStatement	setNamedValues(Map<String,Object> newNamedValues) Shortcut for setNamedValuesWithIds(Map) with raw strings as value names.
SimpleStatement	setNamedValuesWithIds(Map<CqlIdentifier,Object> newNamedValues) Sets the named values to bind to named placeholders.
SimpleStatement	setPositionalValues(List<Object> newPositionalValues) Sets the positional values to bind to anonymous placeholders.
SimpleStatement	setQuery(String newQuery) Sets the CQL query to execute.

Methods inherited from interface com.datastax.oss.driver.api.core.cql.Statement

copy, disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getNowInSeconds, getPageSize, getPagingState, getQueryTimestamp, getSerialConsistencyLevel, isTracing, setConsistencyLevel, setCustomPayload, setDefaultTimestamp, setExecutionProfile, setExecutionProfileName, setFetchSize, setIdempotent, setNode, setNowInSeconds, setPageSize, setPagingState, setPagingState, setPagingState, setQueryTimestamp, setRoutingKey, setRoutingKey, setRoutingKeyspace, setRoutingKeyspace, setRoutingToken, setSerialConsistencyLevel, setTimeout, setTracing

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

getCustomPayload, getExecutionProfile, getExecutionProfileName, getKeyspace, getNode, getPartitioner, getRoutingKey, getRoutingKeyspace, getRoutingToken, getTimeout, isIdempotent

Method Detail

newInstance

static SimpleStatement newInstance(@NonNull
                                   String cqlQuery)

Shortcut to create an instance of the default implementation with only a CQL query (see SimpleStatementBuilder for the defaults for the other fields).

Note that the returned object is immutable.

newInstance

static SimpleStatement newInstance(@NonNull
                                   String cqlQuery,
                                   @NonNull
                                   Object... positionalValues)

Shortcut to create an instance of the default implementation with only a CQL query and positional values (see SimpleStatementBuilder for the defaults for the other fields).

Note that the returned object is immutable.

Parameters:

positionalValues - the values for placeholders in the query string. Individual values can be null, but the vararg array itself can't.

newInstance

static SimpleStatement newInstance(@NonNull
                                   String cqlQuery,
                                   @NonNull
                                   Map<String,Object> namedValues)

Shortcut to create an instance of the default implementation with only a CQL query and named values (see SimpleStatementBuilder for the defaults for other fields).

Note that the returned object is immutable.

builder

@NonNull
static SimpleStatementBuilder builder(@NonNull
                                               String query)

Returns a builder to create an instance of the default implementation.

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

builder

@NonNull
static SimpleStatementBuilder builder(@NonNull
                                               SimpleStatement template)

Returns a builder to create an instance of the default implementation, copying the fields of the given statement.

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

getQuery

@NonNull
String getQuery()

setQuery

@NonNull
SimpleStatement setQuery(@NonNull
                                  String newQuery)

Sets the CQL query to execute.

It may contain anonymous placeholders identified by a question mark, as in:

   SELECT username FROM user WHERE id = ?
 

Or named placeholders prefixed by a column, as in:

   SELECT username FROM user WHERE id = :i
 

The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

See Also:

setPositionalValues(List), setNamedValuesWithIds(Map)

setKeyspace

@NonNull
SimpleStatement setKeyspace(@Nullable
                                     CqlIdentifier newKeyspace)

Sets the CQL keyspace to associate with the query.

This feature is only available with native protocol v5 or higher. Specifying a per-request keyspace with lower protocol versions will cause a runtime error.

See Also:

Request.getKeyspace()

setKeyspace

@NonNull
default SimpleStatement setKeyspace(@NonNull
                                             String newKeyspaceName)

Shortcut for setKeyspace(CqlIdentifier.fromCql(newKeyspaceName)).

getPositionalValues

@NonNull
List<Object> getPositionalValues()

setPositionalValues

@NonNull
SimpleStatement setPositionalValues(@NonNull
                                             List<Object> newPositionalValues)

Sets the positional values to bind to anonymous placeholders.

You can use either positional or named values, but not both. Therefore if you call this method but getNamedValues() returns a non-empty map, an IllegalArgumentException will be thrown.

The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

See Also:

setQuery(String)

getNamedValues

@NonNull
Map<CqlIdentifier,Object> getNamedValues()

setNamedValuesWithIds

@NonNull
SimpleStatement setNamedValuesWithIds(@NonNull
                                               Map<CqlIdentifier,Object> newNamedValues)

Sets the named values to bind to named placeholders.

Names must be stripped of the leading column.

You can use either positional or named values, but not both. Therefore if you call this method but getPositionalValues() returns a non-empty list, an IllegalArgumentException will be thrown.

The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

See Also:

setQuery(String)

setNamedValues

@NonNull
default SimpleStatement setNamedValues(@NonNull
                                                Map<String,Object> newNamedValues)

Shortcut for setNamedValuesWithIds(Map) with raw strings as value names. The keys are converted on the fly with CqlIdentifier.fromCql(String).

computeSizeInBytes

default int computeSizeInBytes(@NonNull
                               DriverContext context)

Description copied from interface: Statement

Calculates the approximate size in bytes that the statement will have when encoded.

The size might be over-estimated by a few bytes due to global options that may be defined on a Session but not explicitly set on the statement itself.

The result of this method is not cached, calling it will cause some encoding to be done in order to determine some of the statement's attributes sizes. Therefore, use this method sparingly in order to avoid unnecessary computation.

Specified by:

computeSizeInBytes in interface Statement<SimpleStatement>

Returns:

the approximate number of bytes this statement will take when encoded.