public class BatchStatement extends Statement
Statement
so they get executed as a batch.
Note: BatchStatement is not supported with the native protocol version 1: you will get an
UnsupportedFeatureException
when submitting one if version 1 of the protocol 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). Note however that you can still use CQL Batch statements even with
the protocol version 1.
Setting a BatchStatement's serial consistency level is only supported with the native protocol
version 3 or higher (see setSerialConsistencyLevel(ConsistencyLevel)
).
Modifier and Type | Class and Description |
---|---|
static class |
BatchStatement.Type
The type of batch to use.
|
idempotent, NULL_PAYLOAD_VALUE
Constructor and Description |
---|
BatchStatement()
Creates a new
LOGGED batch statement. |
BatchStatement(BatchStatement.Type batchType)
Creates a new batch statement of the provided type.
|
Modifier and Type | Method and Description |
---|---|
BatchStatement |
add(Statement statement)
Adds a new statement to this batch.
|
BatchStatement |
addAll(Iterable<? extends Statement> statements)
Adds multiple statements to this batch.
|
BatchStatement |
clear()
Clears this batch, removing all statements added so far.
|
String |
getKeyspace()
Returns the keyspace this query operates on.
|
ByteBuffer |
getRoutingKey(ProtocolVersion protocolVersion,
CodecRegistry codecRegistry)
Returns the routing key (in binary raw form) to use for token aware routing of this query.
|
Collection<Statement> |
getStatements()
The statements that have been added to this batch so far.
|
Boolean |
isIdempotent()
Whether this statement is idempotent, i.e.
|
int |
requestSizeInBytes(ProtocolVersion protocolVersion,
CodecRegistry codecRegistry)
Returns the number of bytes required to encode this statement.
|
BatchStatement |
setSerialConsistencyLevel(ConsistencyLevel serialConsistency)
Sets the serial consistency level for the query.
|
int |
size()
Returns the number of elements in this batch.
|
disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getHost, getNowInSeconds, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getSerialConsistencyLevel, isBatchIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, setHost, setIdempotent, setNowInSeconds, setOutgoingPayload, setPagingState, setPagingState, setPagingStateUnsafe, setReadTimeoutMillis, setRetryPolicy
public BatchStatement()
LOGGED
batch statement.public BatchStatement(BatchStatement.Type batchType)
batchType
- the type of batch.public BatchStatement add(Statement statement)
Note that statement
can be any Statement
. It is allowed to mix RegularStatement
and BoundStatement
in the same BatchStatement
in particular.
Adding another BatchStatement
is also allowed for convenience and is equivalent to
adding all the Statement
contained in that other BatchStatement
.
Due to a protocol-level limitation, adding a RegularStatement
with named values is
currently not supported; an IllegalArgument
will be thrown.
When adding a BoundStatement
, all of its values must be set, otherwise an IllegalStateException
will be thrown when submitting the batch statement. See BoundStatement
for more details, in particular how to handle null
values.
Please note that the options of the added Statement (all those defined directly by the
Statement
class: consistency level, fetch size, tracing, ...) will be ignored for the
purpose of the execution of the Batch. Instead, the options used are the one of this BatchStatement
object.
statement
- the new statement to add.IllegalStateException
- if adding the new statement means that this BatchStatement
has more than 65536 statements (since this is the maximum number of
statements for a BatchStatement allowed by the underlying protocol).IllegalArgumentException
- if adding a regular statement that uses named values.public BatchStatement addAll(Iterable<? extends Statement> statements)
This is a shortcut method that calls add(com.datastax.driver.core.Statement)
on all the statements from statements
.
statements
- the statements to add.public Collection<Statement> getStatements()
public BatchStatement clear()
BatchStatement
.public int size()
public int requestSizeInBytes(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
Statement
The calculated size may be overestimated by a few bytes, but is never underestimated. If the size cannot be calculated, this method returns -1.
Note that the returned value is not cached, but instead recomputed at every method call.
requestSizeInBytes
in class Statement
public BatchStatement setSerialConsistencyLevel(ConsistencyLevel serialConsistency)
This is only supported with version 3 or higher of the native protocol. If you call this
method when version 2 is in use, you will get an UnsupportedFeatureException
when
submitting the statement. With version 2, protocol batches with conditions have their serial
consistency level hardcoded to SERIAL; if you need to execute a batch with LOCAL_SERIAL, you
will have to use a CQL batch.
setSerialConsistencyLevel
in class Statement
serialConsistency
- the serial consistency level to set.Statement
object.IllegalArgumentException
- if serialConsistency
is not one of ConsistencyLevel.SERIAL
or ConsistencyLevel.LOCAL_SERIAL
.Statement.setSerialConsistencyLevel(ConsistencyLevel)
public ByteBuffer getRoutingKey(ProtocolVersion protocolVersion, CodecRegistry codecRegistry)
Statement
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.
getRoutingKey
in class Statement
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.null
.public String getKeyspace()
Statement
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.
getKeyspace
in class Statement
null
.public Boolean isIdempotent()
Statement
If a statement is not idempotent, the driver will ensure that it never gets executed more than once, which means:
retries
on write timeouts or request errors;
speculative executions
.
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
:
Statement.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 PreparedStatement
s created from it.
isIdempotent
in class Statement
null
to use QueryOptions.getDefaultIdempotence()
.Copyright © 2012–2023. All rights reserved.