Statement (DataStax Enterprise Java Driver - Binary distribution 1.5.1 API)

java.lang.Object
- com.datastax.driver.core.Statement

Direct Known Subclasses:

BatchStatement, BoundStatement, RegularStatement, StatementWrapper
```
public abstract class Statement
extends Object
```
An executable query.
This represents either a RegularStatement, a BoundStatement or a BatchStatement along with the querying options (consistency level, whether to trace the query, ...).

Field Summary

Fields
Modifier and Type	Field and Description
`protected Boolean`	`idempotent`
`static ByteBuffer`	`NULL_PAYLOAD_VALUE` A special ByteBuffer value that can be used with custom payloads to denote a null value in a payload map.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Statement`	`disableTracing()` Disables tracing for this query.
`Statement`	`enableTracing()` Enables tracing for this query.
`Statement`	`executingAs(String userOrRole)` Allows this statement to be executed as a different user/role than the one currently authenticated (a.k.a.
`ConsistencyLevel`	`getConsistencyLevel()` The consistency level for this query.
`long`	`getDefaultTimestamp()` The default timestamp for this query.
`int`	`getFetchSize()` The fetch size for this query.
`abstract String`	`getKeyspace()` Returns the keyspace this query operates on.
`Map<String,ByteBuffer>`	`getOutgoingPayload()` Returns this statement's outgoing payload.
`int`	`getReadTimeoutMillis()` Return the per-host read timeout that was set for this statement.
`RetryPolicy`	`getRetryPolicy()` Returns the retry policy sets for this query, if any.
`abstract ByteBuffer`	`getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)` Returns the routing key (in binary raw form) to use for token aware routing of this query.
`Token`	`getRoutingToken()` Returns the routing token to use for token aware routing of this query.
`ConsistencyLevel`	`getSerialConsistencyLevel()` The serial consistency level for this query.
`protected static Boolean`	`isBatchIdempotent(Collection<? extends Statement> statements)`
`Boolean`	`isIdempotent()` Whether this statement is idempotent, i.e.
`boolean`	`isTracing()` Returns whether tracing is enabled for this query or not.
`Statement`	`setConsistencyLevel(ConsistencyLevel consistency)` Sets the consistency level for the query.
`Statement`	`setDefaultTimestamp(long defaultTimestamp)` Sets the default timestamp for this query (in microseconds since the epoch).
`Statement`	`setFetchSize(int fetchSize)` Sets the query fetch size.
`Statement`	`setIdempotent(boolean idempotent)` Sets whether this statement is idempotent.
`Statement`	`setOutgoingPayload(Map<String,ByteBuffer> payload)` Set the given outgoing payload on this statement.
`Statement`	`setPagingState(PagingState pagingState)` Sets the paging state.
`Statement`	`setPagingState(PagingState pagingState, CodecRegistry codecRegistry)` Sets the paging state.
`Statement`	`setPagingStateUnsafe(byte[] pagingState)` Sets the paging state.
`Statement`	`setReadTimeoutMillis(int readTimeoutMillis)` Overrides the default per-host read timeout (`SocketOptions.getReadTimeoutMillis()`) for this statement.
`Statement`	`setRetryPolicy(RetryPolicy policy)` Sets the retry policy to use for this query.
`Statement`	`setSerialConsistencyLevel(ConsistencyLevel serialConsistency)` Sets the serial consistency level for the query.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NULL_PAYLOAD_VALUE
```
public static final ByteBuffer NULL_PAYLOAD_VALUE
```
    A special ByteBuffer value that can be used with custom payloads to denote a null value in a payload map.
  - idempotent
```
protected volatile Boolean idempotent
```
- Method Detail
  - setConsistencyLevel
```
public Statement setConsistencyLevel(ConsistencyLevel consistency)
```
    Sets the consistency level for the query.
    
    Parameters:
    
    consistency - the consistency level to set.
    
    Returns:
    
    this Statement object.
  - getConsistencyLevel
```
public ConsistencyLevel getConsistencyLevel()
```
    The consistency level for this query.
    
    Returns:
    
    the consistency level for this query, or null if no consistency level has been specified (through setConsistencyLevel). In the latter case, the default consistency level will be used.
  - setSerialConsistencyLevel
```
public Statement setSerialConsistencyLevel(ConsistencyLevel serialConsistency)
```
    Sets the serial consistency level for the query.
    The serial consistency level is only used by conditional updates (INSERT, UPDATE or DELETE statements with an IF condition). For those, the serial consistency level defines the consistency level of the serial phase (or "paxos" phase) while the normal consistency level defines the consistency for the "learn" phase, i.e. what type of reads will be guaranteed to see the update right away. For instance, if a conditional write has a regular consistency of QUORUM (and is successful), then a QUORUM read is guaranteed to see that write. But if the regular consistency of that write is ANY, then only a read with a consistency of SERIAL is guaranteed to see it (even a read with consistency ALL is not guaranteed to be enough).
    The serial consistency can only be one of ConsistencyLevel.SERIAL or ConsistencyLevel.LOCAL_SERIAL. While ConsistencyLevel.SERIAL guarantees full linearizability (with other SERIAL updates), ConsistencyLevel.LOCAL_SERIAL only guarantees it in the local data center.
    The serial consistency level is ignored for any query that is not a conditional update (serial reads should use the regular consistency level for instance).
    
    Parameters:
    
    serialConsistency - the serial consistency level to set.
    
    Returns:
    
    this Statement object.
    
    Throws:
    
    IllegalArgumentException - if serialConsistency is not one of ConsistencyLevel.SERIAL or ConsistencyLevel.LOCAL_SERIAL.
  - getSerialConsistencyLevel
```
public ConsistencyLevel getSerialConsistencyLevel()
```
    The serial consistency level for this query.
    See setSerialConsistencyLevel(ConsistencyLevel) for more detail on the serial consistency level.
    
    Returns:
    
    the serial consistency level for this query, or null if no serial consistency level has been specified (through setSerialConsistencyLevel(ConsistencyLevel)). In the latter case, the default serial consistency level will be used.
  - enableTracing
```
public Statement enableTracing()
```
    Enables tracing for this query.
    By default (that is unless you call this method), tracing is not enabled.
    
    Returns:
    
    this Statement object.
  - disableTracing
```
public Statement disableTracing()
```
    Disables tracing for this query.
    
    Returns:
    
    this Statement object.
  - isTracing
```
public boolean isTracing()
```
    Returns whether tracing is enabled for this query or not.
    
    Returns:
    
    true if this query has tracing enabled, false otherwise.
  - getRoutingKey
```
public abstract ByteBuffer getRoutingKey(ProtocolVersion protocolVersion,
                                         CodecRegistry codecRegistry)
```
    Returns the routing key (in binary raw form) to use for token aware routing of this query.
    The routing key is optional in that implementers are free to return null. The routing key is an hint used for token-aware routing (see TokenAwarePolicy), and if provided should correspond to the binary value for the query partition key. However, not providing a routing key never causes a query to fail and if the load balancing policy used is not token aware, then the routing key can be safely ignored.
    
    Parameters:
    
    protocolVersion - the protocol version that will be used if the actual implementation needs to serialize something to compute the key.
    
    codecRegistry - the codec registry that will be used if the actual implementation needs to serialize something to compute this key.
    
    Returns:
    
    the routing key for this query or null.
  - getRoutingToken
```
public Token getRoutingToken()
```
    Returns the routing token to use for token aware routing of this query.
    This is similar to getRoutingKey(ProtocolVersion, CodecRegistry), except that the key is already hashed. A typical use case would be analytics clients wishing to optimize a query by splitting it into chunks, each targeted to a direct replica. Such clients could call Metadata.getTokenRanges() to get a description of the ring, and then issue a separate query with the end token of each range. Unlike the routing key, the routing token is never computed automatically.
    If both the routing key and token are defined, the token is used in priority.
    
    Returns:
    
    an optional routing token for this statement or null.
  - getKeyspace
```
public abstract String getKeyspace()
```
    Returns the keyspace this query operates on.
    Note that not all query specify on which keyspace they operate on, and so this method can always return null. Firstly, some queries do not operate inside a keyspace: keyspace creation, USE queries, user creation, etc. Secondly, even query that operate within a keyspace do not have to specify said keyspace directly, in which case the currently logged in keyspace (the one set through a USE query (or through the use of Cluster.connect(String))). Lastly, as for the routing key, this keyspace information is only a hint for token-aware routing (since replica placement depend on the replication strategy in use which is a per-keyspace property) and having this method return null (or even a bogus keyspace name) will never cause the query to fail.
    
    Returns:
    
    the keyspace this query operate on if relevant or null.
  - setRetryPolicy
```
public Statement setRetryPolicy(RetryPolicy policy)
```
    Sets the retry policy to use for this query.
    The default retry policy, if this method is not called, is the one returned by Policies.getRetryPolicy() in the cluster configuration. This method is thus only useful in case you want to punctually override the default policy for this request.
    
    Parameters:
    
    policy - the retry policy to use for this query.
    
    Returns:
    
    this Statement object.
  - getRetryPolicy
```
public RetryPolicy getRetryPolicy()
```
    Returns the retry policy sets for this query, if any.
    
    Returns:
    
    the retry policy sets specifically for this query or null if no query specific retry policy has been set through setRetryPolicy(com.datastax.driver.core.policies.RetryPolicy) (in which case the Cluster retry policy will apply if necessary).
  - setFetchSize
```
public Statement setFetchSize(int fetchSize)
```
    Sets the query fetch size.
    The fetch size controls how much resulting rows will be retrieved simultaneously (the goal being to avoid loading too much results in memory for queries yielding large results). Please note that while value as low as 1 can be used, it is *highly* discouraged to use such a low value in practice as it will yield very poor performance. If in doubt, leaving the default is probably a good idea.
    Only SELECT queries only ever make use of that setting.
    Note: Paging is not supported with the native protocol version 1. If you call this method with fetchSize > 0 and fetchSize != Integer.MAX_VALUE and the protocol version is in use (i.e. if you've force version 1 through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion) or you use Cassandra 1.2), you will get UnsupportedProtocolVersionException when submitting this statement for execution.
    
    Parameters:
    
    fetchSize - the fetch size to use. If fetchSize &lte; 0, the default fetch size will be used. To disable paging of the result set, use fetchSize == Integer.MAX_VALUE.
    
    Returns:
    
    this Statement object.
  - getFetchSize
```
public int getFetchSize()
```
    The fetch size for this query.
    
    Returns:
    
    the fetch size for this query. If that value is less or equal to 0 (the default unless setFetchSize(int) is used), the default fetch size will be used.
  - setDefaultTimestamp
```
public Statement setDefaultTimestamp(long defaultTimestamp)
```
    Sets the default timestamp for this query (in microseconds since the epoch).
    This feature is only available when version V3 or higher of the native protocol is in use. With earlier versions, calling this method has no effect.
    The actual timestamp that will be used for this query is, in order of preference:
    - the timestamp specified directly in the CQL query string (using the USING TIMESTAMP syntax);
    - the timestamp specified through this method, if different from Long.MIN_VALUE;
    - the timestamp returned by the TimestampGenerator currently in use, if different from Long.MIN_VALUE.
    If none of these apply, no timestamp will be sent with the query and Cassandra will generate a server-side one (similar to the pre-V3 behavior).
    Parameters:
    
    defaultTimestamp - the default timestamp for this query (must be strictly positive).
    
    Returns:
    
    this Statement object.
    
    See Also:
    
    Cluster.Builder.withTimestampGenerator(TimestampGenerator)
  - getDefaultTimestamp
```
public long getDefaultTimestamp()
```
    The default timestamp for this query.
    
    Returns:
    
    the default timestamp (in microseconds since the epoch).
  - setReadTimeoutMillis
```
public Statement setReadTimeoutMillis(int readTimeoutMillis)
```
    Overrides the default per-host read timeout (SocketOptions.getReadTimeoutMillis()) for this statement.
    You should override this only for statements for which the coordinator may allow a longer server-side timeout (for example aggregation queries).
    
    Parameters:
    
    readTimeoutMillis - the timeout to set. Negative values are not allowed. If it is 0, the read timeout will be disabled for this statement.
    
    Returns:
    
    this Statement object.
  - getReadTimeoutMillis
```
public int getReadTimeoutMillis()
```
    Return the per-host read timeout that was set for this statement.
    
    Returns:
    
    the timeout. Note that a negative value means that the default SocketOptions.getReadTimeoutMillis() will be used.
  - setPagingState
```
public Statement setPagingState(PagingState pagingState,
                                CodecRegistry codecRegistry)
```
    Sets the paging state.
    This will cause the next execution of this statement to fetch results from a given page, rather than restarting from the beginning.
    You get the paging state from a previous execution of the statement (see ExecutionInfo.getPagingState(). This is typically used to iterate in a "stateless" manner (e.g. across HTTP requests):
```
 
 Statement st = new SimpleStatement("your query");
 ResultSet rs = session.execute(st.setFetchSize(20));
 int available = rs.getAvailableWithoutFetching();
 for (int i = 0; i < available; i++) {
     Row row = rs.one();
     // Do something with row (e.g. display it to the user...)
 }
 // Get state and serialize as string or byte[] to store it for the next execution
 // (e.g. pass it as a parameter in the "next page" URI)
 PagingState pagingState = rs.getExecutionInfo().getPagingState();
 String savedState = pagingState.toString();

 // Next execution:
 // Get serialized state back (e.g. get URI parameter)
 String savedState = ...
 Statement st = new SimpleStatement("your query");
 st.setPagingState(PagingState.fromString(savedState));
 ResultSet rs = session.execute(st.setFetchSize(20));
 int available = rs.getAvailableWithoutFetching();
 for (int i = 0; i < available; i++) {
     ...
 }
 
 
```
    The paging state can only be reused between perfectly identical statements (same query string, same bound parameters). Altering the contents of the paging state or trying to set it on a different statement will cause this method to fail.
    Note that, due to internal implementation details, the paging state is not portable across native protocol versions (see the online documentation for more explanations about the native protocol). This means that PagingState instances generated with an old version won't work with a higher version. If that is a problem for you, consider using the "unsafe" API (see setPagingStateUnsafe(byte[])).
    Parameters:
    
    pagingState - the paging state to set, or null to remove any state that was previously set on this statement.
    
    codecRegistry - the codec registry that will be used if this method needs to serialize the statement's values in order to check that the paging state matches.
    
    Returns:
    
    this Statement object.
    
    Throws:
    
    PagingStateException - if the paging state does not match this statement.
    
    See Also:
    
    setPagingState(PagingState)
  - setPagingState
```
public Statement setPagingState(PagingState pagingState)
```
    Sets the paging state.
    This method calls setPagingState(PagingState, CodecRegistry) with CodecRegistry.DEFAULT_INSTANCE. Whether you should use this or the other variant depends on the type of statement this is called on:
    - for a BoundStatement, the codec registry isn't actually needed, so it's always safe to use this method;
    - for a SimpleStatement or BuiltStatement, you can use this method if you use no custom codecs, or if your custom codecs are registered with the default registry. Otherwise, use the other method and provide the registry that contains your codecs.
    Parameters:
    
    pagingState - the paging state to set, or null to remove any state that was previously set on this statement.
  - setPagingStateUnsafe
```
public Statement setPagingStateUnsafe(byte[] pagingState)
```
    Sets the paging state.
    Contrary to setPagingState(PagingState), this method takes the "raw" form of the paging state (previously extracted with ExecutionInfo.getPagingStateUnsafe(). It won't validate that this statement matches the one that the paging state was extracted from. If the paging state was altered in any way, you will get unpredictable behavior from Cassandra (ranging from wrong results to a query failure). If you decide to use this variant, it is strongly recommended to add your own validation (for example, signing the raw state with a private key).
    
    Parameters:
    
    pagingState - the paging state to set, or null to remove any state that was previously set on this statement.
    
    Returns:
    
    this Statement object.
  - setIdempotent
```
public Statement setIdempotent(boolean idempotent)
```
    Sets whether this statement is idempotent.
    See isIdempotent() for more explanations about this property.
    
    Parameters:
    
    idempotent - the new value.
    
    Returns:
    
    this Statement object.
  - isIdempotent
```
public Boolean isIdempotent()
```
    Whether this statement is idempotent, i.e. whether it can be applied multiple times without changing the result beyond the initial application.
    If a statement is not idempotent, the driver will ensure that it never gets executed more than once, which means:
    - avoiding retries on write timeouts or request errors;
    - never scheduling speculative executions.
    (this behavior is implemented in the driver internals, the corresponding policies will not even be invoked).
    Note that this method can return null, in which case the driver will default to QueryOptions.getDefaultIdempotence().
    By default, this method returns null for all statements, except for
    - BuiltStatement - value will be inferred from the query: if it updates counters, prepends/appends to a list, or uses a function call or QueryBuilder.raw(String) anywhere in an inserted value, the result will be false; otherwise it will be true.
    - Batch and BatchStatement:
      
      If any statement in batch has isIdempotent() false - return false
      
      If no statements with isIdempotent() false, but some have isIdempotent() null - return null
      
      Otherwise - return true
    In all cases, calling setIdempotent(boolean) forces a value that overrides calculated value.
    Note that when a statement is prepared (Session.prepare(String)), its idempotence flag will be propagated to all PreparedStatements created from it.
    Returns:
    
    whether this statement is idempotent, or null to use QueryOptions.getDefaultIdempotence().
  - getOutgoingPayload
```
public Map<String,ByteBuffer> getOutgoingPayload()
```
    Returns this statement's outgoing payload. Each time this statement is executed, this payload will be included in the query request.
    This method returns null if no payload has been set, otherwise it always returns immutable maps.
    This feature is only available with ProtocolVersion.V4 or above. Trying to include custom payloads in requests sent by the driver under lower protocol versions will result in an UnsupportedFeatureException (wrapped in a NoHostAvailableException).
    
    Returns:
    
    the outgoing payload to include with this statement, or null if no payload has been set.
    
    Since:
    
    2.2
  - setOutgoingPayload
```
public Statement setOutgoingPayload(Map<String,ByteBuffer> payload)
```
    Set the given outgoing payload on this statement. Each time this statement is executed, this payload will be included in the query request.
    This method makes a defensive copy of the given map, but its values remain inherently mutable. Care should be taken not to modify the original map once it is passed to this method.
    This feature is only available with ProtocolVersion.V4 or above. Trying to include custom payloads in requests sent by the driver under lower protocol versions will result in an UnsupportedFeatureException (wrapped in a NoHostAvailableException).
    
    Parameters:
    
    payload - the outgoing payload to include with this statement, or null to clear any previously entered payload.
    
    Returns:
    
    this Statement object.
    
    Since:
    
    2.2
  - isBatchIdempotent
```
protected static Boolean isBatchIdempotent(Collection<? extends Statement> statements)
```
  - executingAs
```
public Statement executingAs(String userOrRole)
```
    Allows this statement to be executed as a different user/role than the one currently authenticated (a.k.a. proxy execution).
    This feature is only available in DSE 5.1+.
    
    Parameters:
    
    userOrRole - The user or role name to act as when executing this statement.

Class Statement

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NULL_PAYLOAD_VALUE

idempotent

Method Detail

setConsistencyLevel

getConsistencyLevel

setSerialConsistencyLevel

getSerialConsistencyLevel

enableTracing

disableTracing

isTracing

getRoutingKey

getRoutingToken

getKeyspace

setRetryPolicy

getRetryPolicy

setFetchSize

getFetchSize

setDefaultTimestamp

getDefaultTimestamp

setReadTimeoutMillis

getReadTimeoutMillis

setPagingState

setPagingState

setPagingStateUnsafe

setIdempotent

isIdempotent

getOutgoingPayload

setOutgoingPayload

isBatchIdempotent

executingAs