|
对于最新的稳定版本，请使用 Spring Data Cassandra 4.4.0！ |
定义查询方法
存储库代理有两种方法可以从方法名称派生特定于存储的查询：
-
通过直接从方法名称派生查询。
-
通过使用手动定义的查询。
可用选项取决于实际商店。 但是，必须有一个策略来决定创建什么实际的查询。 下一节将介绍可用选项。
查询查找策略
存储库基础设施可以使用以下策略来解析查询。
使用 XML 配置，您可以通过query-lookup-strategy属性。
对于 Java 配置，您可以使用queryLookupStrategy属性的EnableCassandraRepositories注解。
某些策略可能不支持特定数据存储。
-
CREATE尝试从查询方法名称构造特定于存储的查询。 一般的方法是从方法名称中删除一组给定的已知前缀，并解析方法的其余部分。 您可以在 “Query Creation” 中阅读有关查询构造的更多信息。 -
USE_DECLARED_QUERY尝试查找已声明的查询，如果找不到，则引发异常。 查询可以通过某处的 Comments 定义，也可以通过其他方式声明。 请参阅特定商店的文档，以查找该商店的可用选项。 如果存储库基础结构在引导时未找到该方法的声明查询，则它将失败。 -
CREATE_IF_NOT_FOUND（默认）组合CREATE和USE_DECLARED_QUERY. 它首先查找已声明的查询，如果未找到已声明的查询，则创建基于自定义方法名称的查询。 这是默认的查找策略，因此，如果您未显式配置任何内容，则使用该策略。 它允许通过方法名称快速定义查询，但也允许通过根据需要引入声明的查询来自定义调整这些查询。
查询创建
Spring Data 存储库基础结构中内置的查询生成器机制对于构建对存储库实体的约束查询非常有用。
以下示例显示如何创建多个查询：
interface PersonRepository extends Repository<Person, Long> {
List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
// Enables the distinct flag for the query
List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);
// Enabling ignoring case for an individual property
List<Person> findByLastnameIgnoreCase(String lastname);
// Enabling ignoring case for all suitable properties
List<Person> findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);
// Enabling static ORDER BY for a query
List<Person> findByLastnameOrderByFirstnameAsc(String lastname);
List<Person> findByLastnameOrderByFirstnameDesc(String lastname);
}解析查询方法名称分为主题和谓词。
第一部分 （find…By,exists…By） 定义查询的主题，则第二部分构成谓词。
引入子句 （subject） 可以包含进一步的表达式。
之间的任何文本find（或其他引入关键字）和By被视为描述性关键字，除非使用结果限制关键字之一，例如Distinct在要创建的查询上设置 distinct 标志，或Top/First限制查询结果.
附录包含查询方法主题关键字和查询方法谓词关键字的完整列表，包括排序和字母大小写修饰符。
然而，第一个By充当分隔符以指示实际条件谓词的开头。
在非常基本的级别上，您可以定义实体属性的条件，并将它们与And和Or.
解析方法的实际结果取决于您为其创建查询的持久性存储。 但是，有一些一般事项需要注意：
-
表达式通常是属性遍历与可以连接的运算符组合。 您可以将属性表达式与
AND和OR. 您还可以获得对运算符的支持，例如Between,LessThan,GreaterThan和Like对于属性表达式。 支持的运算符可能因数据存储而异，因此请参阅参考文档的相应部分。 -
方法解析器支持将
IgnoreCase标志（例如findByLastnameIgnoreCase(…)）或支持忽略大小写的类型的所有属性（通常为Stringinstances — 例如findByLastnameAndFirstnameAllIgnoreCase(…)). 是否支持忽略大小写可能因商店而异，因此请参阅参考文档中的相关部分，了解特定于商店的查询方法。 -
您可以通过附加
OrderBy子句添加到引用属性的查询方法中，并通过提供排序方向 （Asc或Desc). 要创建支持动态排序的查询方法，请参阅“分页，迭代大结果，排序和限制”。
保留方法名称
虽然派生的存储库方法按名称绑定到属性，但当涉及到从面向 identifier 属性的基本存储库继承的某些方法名称时，此规则有一些例外。
那些保留的方法，如CrudRepository#findById（或只是findById） 都以 identifier 属性为目标，而不管声明的方法中使用的实际属性名称如何。
请考虑以下持有属性的域类型pk标记为标识符的途径@Id和一个名为id.
在这种情况下，您需要密切注意查找方法的命名，因为它们可能会与预定义的签名发生冲突：
class User {
@Id Long pk; (1)
Long id; (2)
// …
}
interface UserRepository extends Repository<User, Long> {
Optional<User> findById(Long id); (3)
Optional<User> findByPk(Long pk); (4)
Optional<User> findUserById(Long id); (5)
}| 1 | identifier 属性 （primary key）。 |
| 2 | 名为id，但不包括标识符。 |
| 3 | 将pk属性（标有@Id（被视为标识符）时，因为它引用CrudRepositorybase 存储库方法。
因此，它不是使用 ofid正如 property name 所暗示的那样，因为它是 Reserved 方法之一。 |
| 4 | 将pkproperty 的 NAME 来定义它，因为它是一个派生查询。 |
| 5 | 将id属性，在find和by以避免与保留方法发生冲突。 |
这种特殊行为不仅针对查找方法，也适用于exits和delete的。
有关方法列表，请参阅“存储库查询关键字”。
属性表达式
属性表达式只能引用托管实体的直接属性，如前面的示例所示。 在创建查询时，您已确保 parsed 属性是托管域类的属性。 但是，您也可以通过遍历嵌套属性来定义约束。 请考虑以下方法签名：
List<Person> findByAddressZipCode(ZipCode zipCode);假设Person具有Address替换为ZipCode.
在这种情况下，该方法会创建x.address.zipCodeproperty 遍历。
分辨率算法首先解释整个零件 （AddressZipCode） 作为属性，并在 domain 类中检查具有该名称 （uncapitalized） 的属性。
如果算法成功，它将使用该属性。
如果不是，算法将右侧驼峰式部分的源拆分为 head 和 tail，并尝试找到相应的属性 — 在我们的示例中，AddressZip和Code.
如果算法找到具有该 head 的属性，它会获取 tail 并继续从那里构建树，以刚才描述的方式将 tail 向上拆分。
如果第一个分割不匹配，则算法会将分割点向左移动 （Address,ZipCode） 并继续。
尽管这应该适用于大多数情况，但算法可能会选择错误的属性。
假设Person类具有addressZipproperty 也是如此。
该算法在第一轮拆分中已经匹配，选择错误的属性，然后失败（因为addressZip可能没有code属性）。
要解决这种歧义，您可以在方法名称中使用来手动定义遍历点。
所以我们的方法名称将如下所示：_
List<Person> findByAddress_ZipCode(ZipCode zipCode);|
因为我们将下划线 （） 视为保留字符，所以我们强烈建议遵循标准的 Java 命名约定（即，不要在属性名称中使用下划线，而是应用驼峰式大小写）。 |
|
以下划线开头的字段名称：
字段名称可以以下划线开头，例如 大写字段名称：
全大写的字段名称可以这样使用。
嵌套路径（如果适用）需要通过 spliting via 如 第 2 个大写字母的字段名称：
由一个开头的小写字母后跟一个大写字母组成的字段名称，例如 路径歧义：
在下面的示例中，属性的排列 由于首先考虑对属性的直接匹配，因此不会考虑任何可能的嵌套路径，并且算法会选择 |
返回集合或可迭代对象的存储库方法
返回多个结果的查询方法可以使用标准 JavaIterable,List和Set.
除此之外，我们支持返回 Spring Data 的Streamable，则是Iterable以及 Vavr 提供的集合类型。
请参阅附录，其中说明了所有可能的查询方法返回类型。
使用 Streamable 作为查询方法返回类型
您可以使用Streamable作为Iterable或任何集合类型。
它提供了访问非并行Stream（缺少Iterable） 和直接….filter(…)和….map(…)并连接Streamable对其他人：
interface PersonRepository extends Repository<Person, Long> {
Streamable<Person> findByFirstnameContaining(String firstname);
Streamable<Person> findByLastnameContaining(String lastname);
}
Streamable<Person> result = repository.findByFirstnameContaining("av")
.and(repository.findByLastnameContaining("ea"));返回自定义 Streamable 包装器类型
为集合提供专用包装器类型是一种常用的模式，用于为返回多个元素的查询结果提供 API。 通常，通过调用返回类似集合类型的存储库方法并手动创建包装类型的实例来使用这些类型。 你可以避免这个额外的步骤，因为 Spring Data 允许你使用这些包装器类型作为查询方法返回类型，如果它们满足以下条件：
-
该类型实现了
Streamable. -
该类型公开一个构造函数或一个名为
of(…)或valueOf(…)这需要Streamable作为参数。
下面的清单显示了一个示例：
class Product { (1)
MonetaryAmount getPrice() { … }
}
@RequiredArgsConstructor(staticName = "of")
class Products implements Streamable<Product> { (2)
private final Streamable<Product> streamable;
public MonetaryAmount getTotal() { (3)
return streamable.stream()
.map(Product::getPrice)
.reduce(Money.of(0), MonetaryAmount::add);
}
@Override
public Iterator<Product> iterator() { (4)
return streamable.iterator();
}
}
interface ProductRepository implements Repository<Product, Long> {
Products findAllByDescriptionContaining(String text); (5)
}| 1 | 一个Product公开 API 以访问产品价格的实体。 |
| 2 | 一个Streamable<Product>可以通过使用Products.of(…)（使用 Lombok 注释创建的工厂方法）。
采用Streamable<Product>也会这样做。 |
| 3 | 包装器类型公开了一个额外的 API，用于计算Streamable<Product>. |
| 4 | 实现Streamable接口并委托给实际结果。 |
| 5 | 该包装类型Products可以直接用作 Query Method 返回类型。
您无需退货Streamable<Product>并在存储库客户端的查询后手动包装它。 |
支持 Vavr 集合
Vavr 是一个包含 Java 函数式编程概念的库。 它附带了一组自定义的集合类型，您可以将其用作查询方法返回类型，如下表所示：
| Vavr 集合类型 | 使用的 Vavr 实现类型 | 有效的 Java 源类型 |
|---|---|---|
|
|
|
|
|
|
|
|
|
您可以使用第一列（或其子类型）中的类型作为查询方法返回类型，并获取第二列中用作实现类型的类型，具体取决于实际查询结果的 Java 类型（第三列）。
或者，您可以声明Traversable（VavrIterableequivalent），然后从实际的返回值中派生出 implementation 类。
也就是说，一个java.util.List被转换为 VavrList或Seq一个java.util.Set成为 VavrLinkedHashSet Set等。
流式处理查询结果
您可以使用 Java 8 以增量方式处理查询方法的结果Stream<T>作为返回类型。
而不是将查询结果包装在Stream，则使用特定于数据存储的方法执行流式处理，如以下示例所示：
Stream<T>@Query("select u from User u")
Stream<User> findAllByCustomQueryAndStream();
Stream<User> readAllByFirstnameNotNull();
@Query("select u from User u")
Stream<User> streamAllPaged(Pageable pageable);一个Stream可能会包装特定于底层数据存储的资源，因此必须在使用后关闭。
您可以手动关闭Stream通过使用close()方法或使用 Java 7try-with-resources块，如以下示例所示： |
Stream<T>result 中为try-with-resources块try (Stream<User> stream = repository.findAllByCustomQueryAndStream()) {
stream.forEach(…);
}并非所有 Spring Data 模块当前都支持Stream<T>作为返回类型。 |
异步查询结果
您可以使用 Spring 的异步方法运行功能异步运行存储库查询。
这意味着该方法在调用时立即返回，而实际查询发生在已提交给 Spring 的任务中TaskExecutor.
异步查询与反应式查询不同，不应混合使用。
有关反应式支持的更多详细信息，请参阅特定于 store 的文档。
以下示例显示了许多异步查询：
@Async
Future<User> findByFirstname(String firstname); (1)
@Async
CompletableFuture<User> findOneByFirstname(String firstname); (2)| 1 | 用java.util.concurrent.Future作为返回类型。 |
| 2 | 使用 Java 8java.util.concurrent.CompletableFuture作为返回类型。 |
分页，迭代大结果，排序和限制
要处理查询中的参数，请定义方法参数，如前面的示例中所示。
除此之外，基础设施还可以识别某些特定类型，例如Pageable,Sort和Limit，以动态地将分页、排序和限制应用于您的查询。
以下示例演示了这些功能：
Pageable,Slice,Sort和LimitIN 查询方法Page<User> findByLastname(String lastname, Pageable pageable);
Slice<User> findByLastname(String lastname, Pageable pageable);
List<User> findByLastname(String lastname, Sort sort);
List<User> findByLastname(String lastname, Sort sort, Limit limit);
List<User> findByLastname(String lastname, Pageable pageable);采用 APISort,Pageable和Limit期望非null值。
如果您不想应用任何排序或分页，请使用Sort.unsorted(),Pageable.unpaged()和Limit.unlimited(). |
第一种方法允许您传递一个org.springframework.data.domain.Pageable实例添加到 Query 方法中，以动态地将分页添加到静态定义的查询中。
一个Page了解可用元素和页面的总数。
它通过触发 count 查询来计算总数。
由于这可能很昂贵（取决于使用的 store），因此您可以改为返回Slice.
一个Slice只知道下一个Slice可用，这在遍历较大的结果集时可能就足够了。
排序选项通过Pageable实例。
如果只需要排序，请添加org.springframework.data.domain.Sort参数添加到您的方法中。
如您所见，返回List也是可能的。
在这种情况下，构建实际Page实例 （反过来，这意味着不会发出必要的其他 count 查询）。
相反，它将查询限制为仅查找给定的实体范围。
| 要了解整个查询获得多少页，您必须触发额外的 count 查询。 默认情况下，此查询派生自您实际触发的查询。 |
|
特殊参数在查询方法中只能使用一次。
这 |
哪种方法合适？
Spring Data 抽象提供的值可能最好地由下表中概述的可能的查询方法返回类型来显示。 下表显示了您可以从查询方法返回的类型
| 方法 | 提取的数据量 | 查询结构 | 约束 |
|---|---|---|---|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取所有数据可能非常耗时。 |
|
所有结果。 |
单个查询。 |
查询结果可能会耗尽所有内存。获取所有数据可能非常耗时。 |
|
分块（逐个或批量）取决于 |
通常使用游标的单个查询。 |
使用后必须关闭流，以避免资源泄漏。 |
|
|
分块（逐个或批量）取决于 |
通常使用游标的单个查询。 |
Store 模块必须提供响应式基础设施。 |
|
|
一对多查询，从 |
一个
|
|
|
一对多查询，起始位置 |
很多时候，
|
分页和排序
您可以使用属性名称定义简单的排序表达式。 您可以连接表达式以将多个条件收集到一个表达式中。
Sort sort = Sort.by("firstname").ascending()
.and(Sort.by("lastname").descending());要以更类型安全的方法来定义排序表达式，请从要为其定义排序表达式的类型开始，并使用方法引用来定义要排序的属性。
TypedSort<Person> person = Sort.sort(Person.class);
Sort sort = person.by(Person::getFirstname).ascending()
.and(person.by(Person::getLastname).descending());
TypedSort.by(…)通过（通常）使用 CGlib 来使用运行时代理，这在使用 Graal VM Native 等工具时可能会干扰本机映像编译。 |
如果你的 store 实现支持 Querydsl，你也可以使用生成的元模型类型来定义排序表达式：
QSort sort = QSort.by(QPerson.firstname.asc())
.and(QSort.by(QPerson.lastname.desc()));限制查询结果
除了分页之外，还可以使用专用的Limit参数。
您还可以使用First或Topkeywords，您可以互换使用，但不能与Limit参数。
您可以将可选的数值附加到Top或First指定要返回的最大结果大小。
如果省略该数字，则假定结果大小为 1。
以下示例显示如何限制查询大小：
Top和FirstList<User> findByLastname(Limit limit);
User findFirstByOrderByLastnameAsc();
User findTopByOrderByAgeDesc();
Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);
Slice<User> findTop3ByLastname(String lastname, Pageable pageable);
List<User> findFirst10ByLastname(String lastname, Sort sort);
List<User> findTop10ByLastname(String lastname, Pageable pageable);限制表达式还支持Distinct支持不同查询的数据存储的关键字。
此外，对于将结果集限制为一个实例的查询，请使用Optional关键字。
如果将分页或切片应用于限制查询分页（以及可用页数的计算），则会在有限结果中应用该分页或切片。
通过使用Sortparameter 允许您表示 'K' 最小元素和 'K' 最大元素的查询方法。 |