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

Interface Statement<SelfT extends Statement<SelfT>>

Type Parameters:

SelfT - the "self type" used for covariant returns in subtypes.

All Superinterfaces:

Request

All Known Subinterfaces:

BatchableStatement<SelfT>, BatchStatement, BoundStatement, SimpleStatement

public interface Statement<SelfT extends Statement<SelfT>>
extends Request

A request to execute a CQL query.

Field Summary

Fields

Modifier and Type	Field and Description
static GenericType<CompletionStage<AsyncResultSet>>	ASYNC The type returned when a CQL statement is executed asynchronously.
static long	NO_DEFAULT_TIMESTAMP A special value for getQueryTimestamp() that means "no value".
static int	NO_NOW_IN_SECONDS A special value for getNowInSeconds() that means "no value".
static GenericType<ResultSet>	SYNC The type returned when a CQL statement is executed synchronously.

Method Summary

Modifier and Type	Method and Description
int	computeSizeInBytes(DriverContext context) Calculates the approximate size in bytes that the statement will have when encoded.
default SelfT	copy(ByteBuffer newPagingState) Creates a new instance with a different paging state.
ConsistencyLevel	getConsistencyLevel() Returns the ConsistencyLevel to use for the statement.
default int	getNowInSeconds() A custom "now in seconds" to use when applying the request (for testing purposes).
int	getPageSize() Returns the page size to use for the statement.
ByteBuffer	getPagingState() Returns the paging state to send with the statement, or null if this statement has no paging state.
long	getQueryTimestamp() Returns the query timestamp, in microseconds, to send with the statement.
ConsistencyLevel	getSerialConsistencyLevel() Returns the serial ConsistencyLevel to use for the statement.
boolean	isTracing() Whether tracing information should be recorded for this statement.
SelfT	setConsistencyLevel(ConsistencyLevel newConsistencyLevel) Sets the ConsistencyLevel to use for this statement.
SelfT	setCustomPayload(Map<String,ByteBuffer> newCustomPayload) Sets the custom payload to use for execution.
SelfT	setExecutionProfile(DriverExecutionProfile newProfile) Sets the execution profile to use for this statement.
SelfT	setExecutionProfileName(String newConfigProfileName) Sets the name of the execution profile that will be used for this statement.
SelfT	setIdempotent(Boolean newIdempotence) Sets the idempotence to use for execution.
SelfT	setNode(Node node) Sets the Node that should handle this query.
default SelfT	setNowInSeconds(int nowInSeconds) Sets the "now in seconds" to use when applying the request (for testing purposes).
SelfT	setPageSize(int newPageSize) Configures how many rows will be retrieved simultaneously in a single network roundtrip (the goal being to avoid loading too many results in memory at the same time).
SelfT	setPagingState(ByteBuffer newPagingState) Sets the paging state to send with the statement, or null if this statement has no paging state.
SelfT	setQueryTimestamp(long newTimestamp) Sets the query timestamp, in microseconds, to send with the statement.
default SelfT	setRoutingKey(ByteBuffer... newRoutingKeyComponents) Sets the key to use for token-aware routing, when the partition key has multiple components.
SelfT	setRoutingKey(ByteBuffer newRoutingKey) Sets the key to use for token-aware routing.
SelfT	setRoutingKeyspace(CqlIdentifier newRoutingKeyspace) Sets the keyspace to use for token-aware routing.
default SelfT	setRoutingKeyspace(String newRoutingKeyspaceName) Shortcut for setRoutingKeyspace(CqlIdentifier.fromCql(newRoutingKeyspaceName)).
SelfT	setRoutingToken(Token newRoutingToken) Sets the token to use for token-aware routing.
SelfT	setSerialConsistencyLevel(ConsistencyLevel newSerialConsistencyLevel) Sets the serial ConsistencyLevel to use for this statement.
SelfT	setTimeout(Duration newTimeout) Sets how long to wait for this request to complete.
SelfT	setTracing(boolean newTracing) Sets tracing for execution.

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

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

Field Detail

SYNC

static final GenericType<ResultSet> SYNC

The type returned when a CQL statement is executed synchronously.

Most users won't use this explicitly. It is needed for the generic execute method (Session.execute(Request, GenericType)), but CQL statements will generally be run with one of the driver's built-in helper methods (such as SyncCqlSession.execute(Statement)).

ASYNC

static final GenericType<CompletionStage<AsyncResultSet>> ASYNC

The type returned when a CQL statement is executed asynchronously.

Most users won't use this explicitly. It is needed for the generic execute method (Session.execute(Request, GenericType)), but CQL statements will generally be run with one of the driver's built-in helper methods (such as AsyncCqlSession.executeAsync(Statement)).

NO_DEFAULT_TIMESTAMP

static final long NO_DEFAULT_TIMESTAMP

A special value for getQueryTimestamp() that means "no value".

It is equal to Long.MIN_VALUE.

See Also:

Constant Field Values

NO_NOW_IN_SECONDS

static final int NO_NOW_IN_SECONDS

A special value for getNowInSeconds() that means "no value".

It is equal to Integer.MIN_VALUE.

See Also:

Constant Field Values

Method Detail

setExecutionProfileName

@NonNull
 @CheckReturnValue
SelfT setExecutionProfileName(@Nullable
                                                          String newConfigProfileName)

Sets the name of the execution profile that will be used for this statement.

For all the driver's built-in implementations, calling this method with a non-null argument automatically resets Request.getExecutionProfile() to null.

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

setExecutionProfile

@NonNull
 @CheckReturnValue
SelfT setExecutionProfile(@Nullable
                                                      DriverExecutionProfile newProfile)

Sets the execution profile to use for this statement.

For all the driver's built-in implementations, calling this method with a non-null argument automatically resets Request.getExecutionProfileName() to null.

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

setRoutingKeyspace

@NonNull
 @CheckReturnValue
SelfT setRoutingKeyspace(@Nullable
                                                     CqlIdentifier newRoutingKeyspace)

Sets the keyspace to use for token-aware routing.

See Request.getRoutingKey() for a description of the token-aware routing algorithm.

Parameters:

newRoutingKeyspace - The keyspace to use, or null to disable token-aware routing.

setNode

@NonNull
 @CheckReturnValue
SelfT setNode(@Nullable
                                          Node node)

Sets the Node that should handle this query.

In the general case, use of this method is heavily discouraged and should only be used in the following cases:

1. Querying node-local tables, such as tables in the system and system_views keyspaces.
2. Applying a series of schema changes, where it may be advantageous to execute schema changes in sequence on the same node.

Configuring a specific node causes the configured LoadBalancingPolicy to be completely bypassed. However, if the load balancing policy dictates that the node is at distance NodeDistance.IGNORED or there is no active connectivity to the node, the request will fail with a NoNodeAvailableException.

Parameters:

node - The node that should be used to handle executions of this statement or null to delegate to the configured load balancing policy.

setRoutingKeyspace

@NonNull
 @CheckReturnValue
default SelfT setRoutingKeyspace(@Nullable
                                                             String newRoutingKeyspaceName)

Shortcut for setRoutingKeyspace(CqlIdentifier.fromCql(newRoutingKeyspaceName)).

Parameters:

newRoutingKeyspaceName - The keyspace to use, or null to disable token-aware routing.

setRoutingKey

@NonNull
 @CheckReturnValue
SelfT setRoutingKey(@Nullable
                                                ByteBuffer newRoutingKey)

Sets the key to use for token-aware routing.

See Request.getRoutingKey() for a description of the token-aware routing algorithm.

Parameters:

newRoutingKey - The routing key to use, or null to disable token-aware routing.

setRoutingKey

@NonNull
 @CheckReturnValue
default SelfT setRoutingKey(@NonNull
                                                        ByteBuffer... newRoutingKeyComponents)

Sets the key to use for token-aware routing, when the partition key has multiple components.

This method assembles the components into a single byte buffer and passes it to setRoutingKey(ByteBuffer). Neither the individual components, nor the vararg array itself, can be null.

setRoutingToken

@NonNull
 @CheckReturnValue
SelfT setRoutingToken(@Nullable
                                                  Token newRoutingToken)

Sets the token to use for token-aware routing.

See Request.getRoutingKey() for a description of the token-aware routing algorithm.

Parameters:

newRoutingToken - The routing token to use, or null to disable token-aware routing.

setCustomPayload

@NonNull
 @CheckReturnValue
SelfT setCustomPayload(@NonNull
                                                   Map<String,ByteBuffer> newCustomPayload)

Sets the custom payload to use for execution.

All the driver's built-in statement implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance.

Note that it's your responsibility to provide a thread-safe map. This can be achieved with a concurrent or immutable implementation, or by making it effectively immutable (meaning that it's never modified after being set on the statement).

setIdempotent

@NonNull
 @CheckReturnValue
SelfT setIdempotent(@Nullable
                                                Boolean newIdempotence)

Sets the idempotence to use for execution.

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

Parameters:

newIdempotence - a boolean instance to set a statement-specific value, or null to use the default idempotence defined in the configuration.

setTracing

@NonNull
 @CheckReturnValue
SelfT setTracing(boolean newTracing)

Sets tracing for execution.

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

getQueryTimestamp

long getQueryTimestamp()

Returns the query timestamp, in microseconds, to send with the statement.

If this is equal to NO_DEFAULT_TIMESTAMP, the TimestampGenerator configured for this driver instance will be used to generate a timestamp.

See Also:

NO_DEFAULT_TIMESTAMP, TimestampGenerator

setQueryTimestamp

@NonNull
 @CheckReturnValue
SelfT setQueryTimestamp(long newTimestamp)

Sets the query timestamp, in microseconds, to send with the statement.

If this is equal to NO_DEFAULT_TIMESTAMP, the TimestampGenerator configured for this driver instance will be used to generate a timestamp.

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

See Also:

NO_DEFAULT_TIMESTAMP, TimestampGenerator

setTimeout

@NonNull
 @CheckReturnValue
SelfT setTimeout(@Nullable
                                             Duration newTimeout)

Sets how long to wait for this request to complete. This is a global limit on the duration of a session.execute() call, including any retries the driver might do.

Parameters:

newTimeout - the timeout to use, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_TIMEOUT

getPagingState

@Nullable
ByteBuffer getPagingState()

Returns the paging state to send with the statement, or null if this statement has no paging state.

Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.

setPagingState

@NonNull
 @CheckReturnValue
SelfT setPagingState(@Nullable
                                                 ByteBuffer newPagingState)

Sets the paging state to send with the statement, or null if this statement has no paging state.

Paging states are used in scenarios where a paged result is interrupted then resumed later. The paging state can only be reused with the exact same statement (same query string, same parameters). It is an opaque value that is only meant to be collected, stored and re-used. If you try to modify its contents or reuse it with a different statement, the results are unpredictable.

All the driver's built-in implementations are immutable, and return a new instance from this method. However custom implementations may choose to be mutable and return the same instance; if you do so, you must override copy(ByteBuffer).

getPageSize

int getPageSize()

Returns the page size to use for the statement.

Returns:

the set page size, otherwise 0 or a negative value to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_PAGE_SIZE

setPageSize

@NonNull
 @CheckReturnValue
SelfT setPageSize(int newPageSize)

Configures how many rows will be retrieved simultaneously in a single network roundtrip (the goal being to avoid loading too many results in memory at the same time).

Parameters:

newPageSize - the page size to use, set to 0 or a negative value to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_PAGE_SIZE

getConsistencyLevel

@Nullable
ConsistencyLevel getConsistencyLevel()

Returns the ConsistencyLevel to use for the statement.

Returns:

the set consistency, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_CONSISTENCY

setConsistencyLevel

@NonNull
 @CheckReturnValue
SelfT setConsistencyLevel(@Nullable
                                                      ConsistencyLevel newConsistencyLevel)

Sets the ConsistencyLevel to use for this statement.

Parameters:

newConsistencyLevel - the consistency level to use, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_CONSISTENCY

getSerialConsistencyLevel

@Nullable
ConsistencyLevel getSerialConsistencyLevel()

Returns the serial ConsistencyLevel to use for the statement.

Returns:

the set serial consistency, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_SERIAL_CONSISTENCY

setSerialConsistencyLevel

@NonNull
 @CheckReturnValue
SelfT setSerialConsistencyLevel(@Nullable
                                                            ConsistencyLevel newSerialConsistencyLevel)

Sets the serial ConsistencyLevel to use for this statement.

Parameters:

newSerialConsistencyLevel - the serial consistency level to use, or null to use the default value defined in the configuration.

See Also:

DefaultDriverOption.REQUEST_SERIAL_CONSISTENCY

isTracing

boolean isTracing()

Whether tracing information should be recorded for this statement.

getNowInSeconds

default int getNowInSeconds()

A custom "now in seconds" to use when applying the request (for testing purposes).

This method's default implementation returns NO_NOW_IN_SECONDS. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to return the value that was set programmatically (if any).

See Also:

NO_NOW_IN_SECONDS

setNowInSeconds

@NonNull
default SelfT setNowInSeconds(int nowInSeconds)

Sets the "now in seconds" to use when applying the request (for testing purposes).

This method's default implementation returns the statement unchanged. The only reason it exists is to preserve binary compatibility. Internally, the driver overrides it to record the new value.

See Also:

NO_NOW_IN_SECONDS

computeSizeInBytes

int computeSizeInBytes(@NonNull
                       DriverContext context)

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.

Returns:

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

copy

@NonNull
 @CheckReturnValue
default SelfT copy(@Nullable
                                               ByteBuffer newPagingState)

Creates a new instance with a different paging state.

Since all the built-in statement implementations in the driver are immutable, this method's default implementation delegates to setPagingState(ByteBuffer). However, if you write your own mutable implementation, make sure it returns a different instance.