Cassandra-specific Query Methods

本章解释了特定于 Cassandra 的查询方法。此文档使用命令式类型。通过使用响应式返回类型，相同的语义也适用于响应式存储库。

This chapter explains Cassandra-specific query methods. This documentation uses imperative types. By using reactive return types, the same semantics apply to reactive repositories as well.

在存储库上通常触发的多数数据访问操作最终会针对 Apache Cassandra 数据库执行查询。此类查询的定义只是在存储库接口上声明一个方法。以下示例显示多个此类方法声明：

Most of the data access operations you usually trigger on a repository result in a query being executed against the Apache Cassandra database. Defining such a query is a matter of declaring a method on the repository interface. The following example shows a number of such method declarations:

Example 1. PersonRepository with query methods

Imperative

interface PersonRepository extends CrudRepository<Person, String> {

    List<Person> findByLastname(String lastname);                           1

    Slice<Person> findByFirstname(String firstname, Pageable pageRequest);  2

    Window<Person> findByFirstname(String firstname, CassandraScrollPosition pos, Limit limit);  3

    List<Person> findByFirstname(String firstname, QueryOptions opts);      4

    List<Person> findByFirstname(String firstname, Sort sort);              5

    List<Person> findByFirstname(String firstname, Limit limit);            6

    Person findByShippingAddress(Address address);                          7

    Person findFirstByShippingAddress(Address address);                     8

    Stream<Person> findAllBy();                                             9

    @AllowFiltering
    List<Person> findAllByAge(int age);                                     10
}

1	The method shows a query for all people with the given `lastname`. The query is derived from parsing the method name for constraints, which can be concatenated with `And`. Thus, the method name results in a query expression of `SELECT * FROM person WHERE lastname = 'lastname'`.
2	Applies pagination to a query. You can equip your method signature with a `Pageable` parameter and let the method return a `Slice` instance, and we automatically page the query accordingly.
3	Applies scrolling to a query. Scrolling wraps Cassandra’s `PagingState` into `CassandraScrollPosition` and allows dynamic limiting. You can also use `findTop…` for a static limit.
4	Passing a `QueryOptions` object applies the query options to the resulting query before its execution.
5	Applies dynamic sorting to a query. You can add a `Sort` parameter to your method signature, and Spring Data automatically applies ordering to the query.
6	Applies dynamic result limiting to a query. Query results can be limited using `SELECT … LIMIT`.
7	Shows that you can query based on properties that are not a primitive type by using `Converter` instances registered in `CustomConversions`. Throws `IncorrectResultSizeDataAccessException` if more than one match is found.
8	Uses the `First` keyword to restrict the query to only the first result. Unlike the preceding method, this method does not throw an exception if more than one match is found.
9	Uses a Java 8 `Stream` to read and convert individual elements while iterating the stream.
10	Shows a query method annotated with `@AllowFiltering`, to allow server-side filtering. Reactive `interface ReactivePersonRepository extends ReactiveSortingRepository<Person, Long> { Flux<Person> findByFirstname(String firstname); 1 Flux<Person> findByFirstname(Publisher<String> firstname); 2 Mono<Person> findByFirstnameAndLastname(String firstname, String lastname); 3 Mono<Person> findFirstByFirstname(String firstname); 4 @AllowFiltering Flux<Person> findByAge(int age); 5 }`
11	A query for all people with the given `firstname`. The query is derived by parsing the method name for constraints, which can be concatenated with `And` and `Or`. Thus, the method name results in a query expression of `SELECT * FROM person WHERE firstname = :firstname`.
12	A query for all people with the given `firstname` once the `firstname` is emitted from the given `Publisher`.
13	Find a single entity for the given criteria. Completes with `IncorrectResultSizeDataAccessException` on non-unique results.
14	Unlike the preceding query, the first entity is always emitted even if the query yields more result rows.
15	A query method annotated with `@AllowFiltering`, which allows server-side filtering.

查询非主键属性需要二级索引。

Querying non-primary key properties requires secondary indexes.

下表显示了可以在查询方法中使用的关键字的简短示例：

The following table shows short examples of the keywords that you can use in query methods:

Table 1. Supported keywords for query methods
Keyword	Sample	Logical result
`After`	`findByBirthdateAfter(Date date)`	`birthdate > date`
`GreaterThan`	`findByAgeGreaterThan(int age)`	`age > age`
`GreaterThanEqual`	`findByAgeGreaterThanEqual(int age)`	`age >= age`
`Before`	`findByBirthdateBefore(Date date)`	`birthdate < date`
`LessThan`	`findByAgeLessThan(int age)`	`age < age`
`LessThanEqual`	`findByAgeLessThanEqual(int age)`	`age ⇐ age`
`Between`	`findByAgeBetween(int from, int to)` and `findByAgeBetween(Range<Integer> range)`	`age > from AND age < to` and lower / upper bounds (`>` / `>=` & `<` / `⇐`) according to `Range`
`In`	`findByAgeIn(Collection ages)`	`age IN (ages…)`
`Like`, `StartingWith`, `EndingWith`	`findByFirstnameLike(String name)`	`firstname LIKE (name as like expression)`
`Containing` on String	`findByFirstnameContaining(String name)`	`firstname LIKE (name as like expression)`
`Containing` on Collection	`findByAddressesContaining(Address address)`	`addresses CONTAINING address`
`(No keyword)`	`findByFirstname(String name)`	`firstname = name`
`IsTrue`, `True`	`findByActiveIsTrue()`	`active = true`
`IsFalse`, `False`	`findByActiveIsFalse()`	`active = false`

Repository Delete Queries

前表中的关键字可与 delete…By 结合使用，以创建删除匹配文档的查询。

The keywords in the preceding table can be used in conjunction with delete…By to create queries that delete matching documents.

Imperative
Reactive

interface PersonRepository extends Repository<Person, String> {

  void deleteWithoutResultByLastname(String lastname);

  boolean deleteByLastname(String lastname);
}

interface PersonRepository extends Repository<Person, String> {

  Mono<Void> deleteWithoutResultByLastname(String lastname);

  Mono<Boolean> deleteByLastname(String lastname);
}

删除查询返回查询是否已应用或使用 void 终止而不返回值。

Delete queries return whether the query was applied or terminate without returning a value using void.

Query Options

您可以通过传递 QueryOptions 对象为查询方法指定查询选项。这些选项应用于查询在实际查询执行之前。QueryOptions 被视为非查询参数，而不被视为查询参数值。查询选项适用于派生查询和字符串 @Query 存储库方法。

You can specify query options for query methods by passing a QueryOptions object. The options apply to the query before the actual query execution. QueryOptions is treated as a non-query parameter and is not considered to be a query parameter value. Query options apply to derived and string @Query repository methods.

要静态设置一致性级别，请对查询方法使用 @Consistency 注释。每次执行查询时都会应用已声明的一致性级别。以下示例将一致性级别设置为 ConsistencyLevel.LOCAL_ONE：

To statically set the consistency level, use the @Consistency annotation on query methods. The declared consistency level is applied to the query each time it is executed. The following example sets the consistency level to ConsistencyLevel.LOCAL_ONE:

Imperative
Reactive

interface PersonRepository extends CrudRepository<Person, String> {

    @Consistency(ConsistencyLevel.LOCAL_ONE)
    List<Person> findByLastname(String lastname);

    List<Person> findByFirstname(String firstname, QueryOptions options);
}

interface PersonRepository extends ReactiveCrudRepository<Person, String> {

    @Consistency(ConsistencyLevel.LOCAL_ONE)
    Flux<Person> findByLastname(String lastname);

    Flux<Person> findByFirstname(String firstname, QueryOptions options);
}

DataStax Cassandra 文档包括 a good discussion of the available consistency levels。

The DataStax Cassandra documentation includes a good discussion of the available consistency levels.

您可以通过配置 CQL API 实例上的以下参数来控制获取大小、一致性级别和重试策略的默认值： CqlTemplate、AsyncCqlTemplate 和 ReactiveCqlTemplate。如果未设置特定查询选项，则应用默认值。

You can control fetch size, consistency level, and retry policy defaults by configuring the following parameters on the CQL API instances: CqlTemplate, AsyncCqlTemplate, and ReactiveCqlTemplate. Defaults apply if the particular query option is not set.