public interface PreparedStatement
Client applications create instances with SyncCqlSession.prepare(SimpleStatement)
. Then
they use bind(Object...)
to obtain an executable BoundStatement
.
The default prepared statement implementation returned by the driver is thread-safe. Client applications can -- and are expected to -- prepare each query once and store the result in a place where it can be accessed concurrently by application threads (for example a final field). Preparing the same query string twice is suboptimal and a bad practice, and will cause the driver to log a warning.
Modifier and Type | Method and Description |
---|---|
BoundStatement |
bind(Object... values)
Builds an executable statement that associates a set of values with the bind variables.
|
BoundStatementBuilder |
boundStatementBuilder(Object... values)
Returns a builder to construct an executable statement.
|
ByteBuffer |
getId()
A unique identifier for this prepared statement.
|
Partitioner |
getPartitioner()
The partitioner to use for token-aware routing.
|
List<Integer> |
getPartitionKeyIndices()
The indices of the variables in
getVariableDefinitions() that correspond to the target
table's partition key. |
String |
getQuery() |
ByteBuffer |
getResultMetadataId()
A unique identifier for result metadata (essentially a hash of
getResultSetDefinitions() ). |
ColumnDefinitions |
getResultSetDefinitions()
A description of the result set that will be returned when this prepared statement is bound and
executed.
|
ColumnDefinitions |
getVariableDefinitions()
A description of the bind variables of this prepared statement.
|
boolean |
isLWT()
Informs if this is an LWT query.
|
void |
setResultMetadata(ByteBuffer newResultMetadataId,
ColumnDefinitions newResultSetDefinitions)
Updates
getResultMetadataId() and getResultSetDefinitions() atomically. |
@NonNull ByteBuffer getId()
Note: the returned buffer is read-only.
@NonNull String getQuery()
@NonNull ColumnDefinitions getVariableDefinitions()
Partitioner getPartitioner()
null
, the cluster-wide partitioner
will be used.@NonNull List<Integer> getPartitionKeyIndices()
getVariableDefinitions()
that correspond to the target
table's partition key.
This is only present if all the partition key columns are expressed as bind variables. Otherwise, the list will be empty. For example, given the following schema:
CREATE TABLE foo (pk1 int, pk2 int, cc int, v int, PRIMARY KEY ((pk1, pk2), cc));And the following definitions:
PreparedStatement ps1 = session.prepare("UPDATE foo SET v = ? WHERE pk1 = ? AND pk2 = ? AND v = ?"); PreparedStatement ps2 = session.prepare("UPDATE foo SET v = ? WHERE pk1 = 1 AND pk2 = ? AND v = ?");Then
ps1.getPartitionKeyIndices()
contains 1 and 2, and ps2.getPartitionKeyIndices()
is empty (because one of the partition key components is
hard-coded in the query string).@Nullable ByteBuffer getResultMetadataId()
getResultSetDefinitions()
).
This information is mostly for internal use: with protocol DefaultProtocolVersion.V5
or higher, the driver sends it with every execution of the prepared statement, to validate that
its result metadata is still up-to-date.
Note: this method returns null
for protocol DefaultProtocolVersion.V4
or
lower; otherwise, the returned buffer is read-only.
@NonNull ColumnDefinitions getResultSetDefinitions()
This information is only present for SELECT
queries, otherwise it is always empty.
Note that this is slightly incorrect for conditional updates (e.g. INSERT ... IF NOT
EXISTS
), which do return columns; for those cases, use PagingIterable.getColumnDefinitions()
on the result, not this method.
boolean isLWT()
Not guaranteed to return true for LWT queries (but guaranteed to return false for non-LWT ones). It can happen for several reasons, for example: using Cassandra instead of Scylla, using too old Scylla version, future changes in driver allowing channels to be created without sending OPTIONS request.
More information about LWT:
void setResultMetadata(@NonNull ByteBuffer newResultMetadataId, @NonNull ColumnDefinitions newResultSetDefinitions)
getResultMetadataId()
and getResultSetDefinitions()
atomically.
This is for internal use by the driver. Calling this manually with incorrect information can cause existing queries to fail.
@NonNull BoundStatement bind(@NonNull Object... values)
Note that the built-in bound statement implementation is immutable. If you need to set
multiple execution parameters on the bound statement (such as Statement.setExecutionProfileName(String)
, Statement.setPagingState(ByteBuffer)
, etc.), consider using boundStatementBuilder(Object...)
instead to avoid unnecessary allocations.
values
- the values of the bound variables in the statement. You can provide less values
than the actual number of variables (or even none at all), in which case the remaining
variables will be left unset. However, this method will throw an IllegalArgumentException
if there are more values than variables. Individual values can be
null
, but the vararg array itself can't.@NonNull BoundStatementBuilder boundStatementBuilder(@NonNull Object... values)
Note that this builder is mutable and not thread-safe.
bind(Object...)
Copyright © 2017–2024. All rights reserved.