Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
Scylla Java Driver Manual Mapper DAOs Query methods

Query methods¶

Annotate a DAO method with @Query to provide your own query string:

@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 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);

The annotation can define a null saving strategy that applies to the method parameters.

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. See statement attributes.

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 BoundStatement. This is intended for queries where you will execute this statement later or in a batch.

  • a PagingIterable. The method will convert each row into an entity instance.

  • a Stream. The method will convert each row into an entity instance. For details about the stream’s characteristics, see PagingIterable.spliterator.

  • 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.

  • a ReactiveResultSet, or a MappedReactiveResultSet of the entity class.

  • a custom type.

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.

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.

PREVIOUS
Null saving strategy
NEXT
Query provider methods
  • 4.13.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Using the driver in GraalVM native images
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Non-blocking programming
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Query methods
    • Parameters
    • Return type
    • Target keyspace and table
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2