public interface SimpleStatement extends BatchableStatement<SimpleStatement>
To create instances, client applications can use the newInstance
factory methods on
this interface for common cases, or builder(String)
for more control over the
parameters. They can then be passed to SyncCqlSession.execute(Statement)
.
Simple statements should be reserved for queries that will only be executed a few times by an
application. For more frequent queries, PreparedStatement
provides many advantages: it is
more efficient because the server parses the query only once and caches the result; it allows the
server to return metadata about the bind variables, which allows the driver to validate the
values earlier, and apply certain optimizations like token-aware routing.
The default implementation returned by the driver is immutable and thread-safe. All mutating methods return a new instance. See also the static factory methods and builders in this interface.
If an application reuses the same statement more than once, it is recommended to cache it (for example in a final field).
ASYNC, NO_DEFAULT_TIMESTAMP, NO_NOW_IN_SECONDS, SYNC
Modifier and Type | Method and Description |
---|---|
static SimpleStatementBuilder |
builder(SimpleStatement template)
Returns a builder to create an instance of the default implementation, copying the fields of
the given statement.
|
static SimpleStatementBuilder |
builder(String query)
Returns a builder to create an instance of the default implementation.
|
default int |
computeSizeInBytes(DriverContext context)
Calculates the approximate size in bytes that the statement will have when encoded.
|
Map<CqlIdentifier,Object> |
getNamedValues() |
List<Object> |
getPositionalValues() |
String |
getQuery() |
static SimpleStatement |
newInstance(String cqlQuery)
Shortcut to create an instance of the default implementation with only a CQL query (see
SimpleStatementBuilder for the defaults for the other fields). |
static SimpleStatement |
newInstance(String cqlQuery,
Map<String,Object> namedValues)
Shortcut to create an instance of the default implementation with only a CQL query and named
values (see
SimpleStatementBuilder for the defaults for other fields). |
static SimpleStatement |
newInstance(String cqlQuery,
Object... positionalValues)
Shortcut to create an instance of the default implementation with only a CQL query and
positional values (see
SimpleStatementBuilder for the defaults for the other fields). |
SimpleStatement |
setKeyspace(CqlIdentifier newKeyspace)
Sets the CQL keyspace to associate with the query.
|
default SimpleStatement |
setKeyspace(String newKeyspaceName)
Shortcut for
setKeyspace(CqlIdentifier.fromCql(newKeyspaceName)) . |
default SimpleStatement |
setNamedValues(Map<String,Object> newNamedValues)
Shortcut for
setNamedValuesWithIds(Map) with raw strings as value names. |
SimpleStatement |
setNamedValuesWithIds(Map<CqlIdentifier,Object> newNamedValues)
Sets the named values to bind to named placeholders.
|
SimpleStatement |
setPositionalValues(List<Object> newPositionalValues)
Sets the positional values to bind to anonymous placeholders.
|
SimpleStatement |
setQuery(String newQuery)
Sets the CQL query to execute.
|
copy, disableTracing, enableTracing, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getNowInSeconds, getPageSize, getPagingState, getQueryTimestamp, getSerialConsistencyLevel, isLWT, isTracing, setConsistencyLevel, setCustomPayload, setDefaultTimestamp, setExecutionProfile, setExecutionProfileName, setFetchSize, setIdempotent, setNode, setNowInSeconds, setPageSize, setPagingState, setPagingState, setPagingState, setQueryTimestamp, setRoutingKey, setRoutingKey, setRoutingKeyspace, setRoutingKeyspace, setRoutingToken, setSerialConsistencyLevel, setTimeout, setTracing
getCustomPayload, getExecutionProfile, getExecutionProfileName, getKeyspace, getNode, getPartitioner, getRoutingKey, getRoutingKeyspace, getRoutingToken, getTimeout, isIdempotent
static SimpleStatement newInstance(@NonNull String cqlQuery)
SimpleStatementBuilder
for the defaults for the other fields).
Note that the returned object is immutable.
static SimpleStatement newInstance(@NonNull String cqlQuery, @NonNull Object... positionalValues)
SimpleStatementBuilder
for the defaults for the other fields).
Note that the returned object is immutable.
positionalValues
- the values for placeholders in the query string. Individual values can
be null
, but the vararg array itself can't.static SimpleStatement newInstance(@NonNull String cqlQuery, @NonNull Map<String,Object> namedValues)
SimpleStatementBuilder
for the defaults for other fields).
Note that the returned object is immutable.
@NonNull static SimpleStatementBuilder builder(@NonNull String query)
Note that this builder is mutable and not thread-safe.
@NonNull static SimpleStatementBuilder builder(@NonNull SimpleStatement template)
Note that this builder is mutable and not thread-safe.
@NonNull String getQuery()
@NonNull SimpleStatement setQuery(@NonNull String newQuery)
It may contain anonymous placeholders identified by a question mark, as in:
SELECT username FROM user WHERE id = ?Or named placeholders prefixed by a column, as in:
SELECT username FROM user WHERE id = :i
The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
@NonNull SimpleStatement setKeyspace(@Nullable CqlIdentifier newKeyspace)
This feature is only available with native protocol v5
or
higher. Specifying a per-request keyspace with lower protocol versions will cause a runtime
error.
Request.getKeyspace()
@NonNull default SimpleStatement setKeyspace(@NonNull String newKeyspaceName)
setKeyspace(CqlIdentifier.fromCql(newKeyspaceName))
.@NonNull SimpleStatement setPositionalValues(@NonNull List<Object> newPositionalValues)
You can use either positional or named values, but not both. Therefore if you call this
method but getNamedValues()
returns a non-empty map, an IllegalArgumentException
will be thrown.
The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
setQuery(String)
@NonNull Map<CqlIdentifier,Object> getNamedValues()
@NonNull SimpleStatement setNamedValuesWithIds(@NonNull Map<CqlIdentifier,Object> newNamedValues)
Names must be stripped of the leading column.
You can use either positional or named values, but not both. Therefore if you call this
method but getPositionalValues()
returns a non-empty list, an IllegalArgumentException
will be thrown.
The driver's built-in implementation is immutable, and returns a new instance from this method. However custom implementations may choose to be mutable and return the same instance.
setQuery(String)
@NonNull default SimpleStatement setNamedValues(@NonNull Map<String,Object> newNamedValues)
setNamedValuesWithIds(Map)
with raw strings as value names. The keys are
converted on the fly with CqlIdentifier.fromCql(String)
.default int computeSizeInBytes(@NonNull DriverContext context)
Statement
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.
computeSizeInBytes
in interface Statement<SimpleStatement>
Copyright © 2017–2024. All rights reserved.