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

Caution

You're viewing documentation for a previous version of Scylla Java Driver. Switch to the latest stable version.

Scylla Java Driver Manual Mapper DAOs Select methods

Select methods¶

Annotate a DAO method with @Select to generate a query that selects one or more rows, and maps them to Entities:

@Dao
public interface ProductDao {
  @Select
  Product findById(UUID productId);
}

Parameters¶

If the annotation doesn’t have a customWhereClause(), the mapper defaults to a selection by primary key (partition key + clustering columns). The method’s parameters must match the types of the primary key columns, in the exact order (as defined by the @PartitionKey and @ClusteringColumn annotations). The parameter names don’t necessarily need to match the names of the columns.

To select more than one entity within a partition, a subset of primary key components may be specified as long as enough parameters are provided to account for the partition key.

// given: PRIMARY KEY ((product_id, day), customer_id, ts)
public interface ProductSaleDao {
  @Select
  PagingIterable<ProductSale> findByDay(UUID productId, LocalDate day);
  
  @Select
  PagingIterable<ProductSale> findByDayForCustomer(UUID productId, LocalDate day, UUID customerID);
  
  /* Note that the clustering columns in your primary key definition are significant. All
   * preceding clustering columns must be provided if any are.
   *
   * For example, the following is *NOT VALID* because ts is provided, but customer_id is
   * not. */
  @Select
  PagingIterable<ProductSale> findByDayForTs(UUID productId, LocalDate day, long ts);
}

To select all rows within a table, you may also provide no parameters.

@Dao
public interface ProductDao {
  @Select
  PagingIterable<Product> all();
}

If the annotation has a customWhereClause(), it completely replaces the WHERE clause. The provided string can contain named placeholders. In that case, the method must have a corresponding parameter for each, with the same name and a compatible Java type.

@Select(customWhereClause = "description LIKE :searchString")
PagingIterable<Product> findByDescription(String searchString);

The generated SELECT query can be further customized with limit(), perPartitionLimit(), orderBy(), groupBy() and allowFiltering(). Some of these clauses can also contain placeholders whose values will be provided through additional method parameters. Note that it is sometimes not possible to determine if a parameter is a primary key component or a placeholder value; therefore the rule is that if your method takes a partial primary key, the first parameter that is not a primary key component must be explicitly annotated with @CqlName. For example if the primary key is ((day int, hour int, minute int), ts timestamp):

// Annotate 'l' so that it's not mistaken for the second PK component
@Select(limit = ":l")
PagingIterable<Sale> findDailySales(int day, @CqlName("l") int l);

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¶

In all cases, the method can return:

  • the entity class itself. If the query returns no rows, the method will return null. If it returns more than one row, subsequent rows will be discarded.

    @Select
    Product findById(UUID productId);
    
  • an Optional of the entity class. If the query returns no rows, the method will return Optional.empty(). If it returns more than one row, subsequent rows will be discarded.

    @Select
    Optional<Product> findById(UUID productId);
    
  • a PagingIterable of the entity class. It behaves like a result set, except that each element is a mapped entity instead of a row.

    @Select(customWhereClause = "description LIKE :searchString")
    PagingIterable<Product> findByDescription(String searchString);
    
  • a CompletionStage or CompletableFuture of any of the above. The method will execute the query asynchronously. Note that for iterables, you need to switch to the asynchronous equivalent MappedAsyncPagingIterable.

    @Select
    CompletionStage<Product> findByIdAsync(UUID productId);
    
    @Select
    CompletionStage<Optional<Product>> findByIdAsync(UUID productId);
    
    @Select(customWhereClause = "description LIKE :searchString")
    CompletionStage<MappedAsyncPagingIterable<Product>> findByDescriptionAsync(String searchString);
    
  • a MappedReactiveResultSet of the entity class.

    @Select(customWhereClause = "description LIKE :searchString")
    MappedReactiveResultSet<Product> findByDescriptionReactive(String searchString);
    
  • a custom type.

Target keyspace and table¶

If a keyspace was specified when creating the DAO, then the generated query targets that keyspace. Otherwise, it doesn’t specify a keyspace, and will only work if the mapper was built from a session that has a default keyspace set.

If a table was specified when creating the DAO, then the generated query targets that table. Otherwise, it uses the default table name for the entity (which is determined by the name of the entity class and the naming strategy).

PREVIOUS
Query provider methods
NEXT
SetEntity methods
  • 4.10.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
      • 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

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