com.datastax.oss.driver.api.mapper.annotations

Annotation Type Query

@Target(value=METHOD)
 @Retention(value=RUNTIME)
public @interface Query

Annotates a Dao method that executes a user-provided query.

Example:

 @Dao
 public interface SensorReadingDao {
   @Query("SELECT count(*) FROM sensor_readings WHERE id = :id")
   long countById(int id);
 }
 

This is the equivalent of what was called "accessor methods" in the driver 3 mapper.

Parameters

The query string provided in value() will typically contain CQL placeholders. The method's parameters must match those placeholders: same name and a compatible Java type.

 @Query("SELECT count(*) FROM sensor_readings WHERE id = :id AND year = :year")
 long countByIdAndYear(int id, int year);
 

A Function<BoundStatementBuilder, BoundStatementBuilder> or UnaryOperator<BoundStatementBuilder> can be added as the last parameter. It will be applied to the statement before execution. This allows you to customize certain aspects of the request (page size, timeout, etc) at runtime.

Return type

The method can return:

• void.
• a boolean or Boolean, which will be mapped to ResultSet.wasApplied(). This is intended for conditional queries.
• a long or Long, which will be mapped to the first column of the first row, expecting CQL type BIGINT. This is intended for count queries. The method will fail if the result set is empty, or does not match the expected format.
• a Row. This means the result is not converted, the mapper only extracts the first row of the result set and returns it. The method will return null if the result set is empty.
• a single instance of an Entity class. The method will extract the first row and convert it, or return null if the result set is empty.
• an Optional of an entity class. The method will extract the first row and convert it, or return Optional.empty() if the result set is empty.
• a ResultSet. The method will return the raw query result, without any conversion.
• a PagingIterable. The method will convert each row into an entity instance.
• a CompletionStage or CompletableFuture of any of the above. The method will execute the query asynchronously. Note that for result sets and iterables, you need to switch to the asynchronous equivalent AsyncResultSet and MappedAsyncPagingIterable respectively.

Target keyspace and table

To avoid hard-coding the keyspace and table name, the query string supports 3 additional placeholders: ${keyspaceId}, ${tableId} and ${qualifiedTableId}. They get substituted at DAO initialization time, with the keyspace and table that the DAO was built with (see DaoFactory).

For example, given the following:

 @Dao
 public interface TestDao {
   @Query("SELECT * FROM ${keyspaceId}.${tableId}")
   ResultSet queryFromKeyspaceAndTable();

   @Query("SELECT * FROM ${qualifiedTableId}")
   ResultSet queryFromQualifiedTable();
 }

 @Mapper
 public interface TestMapper {
   @DaoFactory
   TestDao dao(@DaoKeyspace String keyspace, @DaoTable String table);

   @DaoFactory
   TestDao dao(@DaoTable String table);
 }

 TestDao dao1 = mapper.dao("ks", "t");
 TestDao dao2 = mapper.dao("t");
 

Then:

• dao1.queryFromKeyspaceAndTable() and dao1.queryFromQualifiedTable() both execute SELECT * FROM ks.t.
• dao2.queryFromKeyspaceAndTable() fails: no keyspace was specified for this DAO, so ${keyspaceId} can't be substituted.
• dao1.queryFromQualifiedTable() executes SELECT * FROM t. In other words, ${qualifiedTableId} uses the keyspace if it is available, but resolves to the table name only if it isn't. Whether the query succeeds or not depends on whether the Session that the mapper was built with has a default keyspace.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String	value The query string to execute.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
NullSavingStrategy	nullSavingStrategy How to handle null query parameters.

Element Detail

value

public abstract String value

The query string to execute.

It can contain CQL placeholders (e.g. :id) that will be bound with the method's parameters; and also special text placeholders ${keyspaceId}, ${tableId} and ${qualifiedTableId} that will be substituted with the keyspace and table that the DAO was built with. See the top-level javadocs of this class for more explanations.

nullSavingStrategy

public abstract NullSavingStrategy nullSavingStrategy

How to handle null query parameters.

This defaults either to the DAO-level strategy (if set), or NullSavingStrategy.DO_NOT_SET.

Default:

com.datastax.oss.driver.api.mapper.entity.saving.NullSavingStrategy.DO_NOT_SET