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

Interface PreparedStatement

public interface PreparedStatement

A query with bind variables that has been pre-parsed by the database.

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.

Method Summary

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.
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.
void	setResultMetadata(ByteBuffer newResultMetadataId, ColumnDefinitions newResultSetDefinitions) Updates getResultMetadataId() and getResultSetDefinitions() atomically.

Method Detail

getId

@NonNull
ByteBuffer getId()

A unique identifier for this prepared statement.

Note: the returned buffer is read-only.

getQuery

@NonNull
String getQuery()

getVariableDefinitions

@NonNull
ColumnDefinitions getVariableDefinitions()

A description of the bind variables of this prepared statement.

getPartitionKeyIndices

@NonNull
List<Integer> getPartitionKeyIndices()

The indices of the variables in 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).

getResultMetadataId

@Nullable
ByteBuffer getResultMetadataId()

A unique identifier for result metadata (essentially a hash of 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.

See Also:

CASSANDRA-10786

getResultSetDefinitions

@NonNull
ColumnDefinitions getResultSetDefinitions()

A description of the result set that will be returned when this prepared statement is bound and executed.

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.

setResultMetadata

void setResultMetadata(@NonNull
                       ByteBuffer newResultMetadataId,
                       @NonNull
                       ColumnDefinitions newResultSetDefinitions)

Updates getResultMetadataId() and getResultSetDefinitions() atomically.

This is for internal use by the driver. Calling this manually with incorrect information can cause existing queries to fail.

bind

@NonNull
BoundStatement bind(@NonNull
                             Object... values)

Builds an executable statement that associates a set of values with the bind variables.

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.

Parameters:

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.

boundStatementBuilder

@NonNull
BoundStatementBuilder boundStatementBuilder(@NonNull
                                                     Object... values)

Returns a builder to construct an executable statement.

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

See Also:

bind(Object...)