跳到主要内容
版本:4.1.1

示例查询

Doubao 中英对照 Query by Example

介绍​

本章介绍示例查询(Query by Example)并说明如何使用它。

示例查询(Query by Example,QBE)是一种用户友好的查询技术,接口简单。它支持动态创建查询,不要求你编写包含字段名的查询。实际上,示例查询根本不要求你使用特定于数据存储的查询语言来编写查询。

备注

本章讲解示例查询的核心概念。这些内容取自 Spring Data Commons 模块。根据你使用的数据库不同,String 匹配支持可能会受限。

用法​

示例查询 API 由四个部分组成:

  • Probe(探测对象):一个填充了字段的领域对象实例。
  • ExampleMatcher:ExampleMatcher 携带如何匹配特定字段的细节。它可以在多个 Example 之间复用。
  • Example:一个 Example 由探测对象和 ExampleMatcher 组成。它用于创建查询。
  • FetchableFluentQuery:FetchableFluentQuery 提供流式 API,可以进一步定制从 Example 派生的查询。使用流式 API 可以为你的查询指定排序投影和结果处理方式。

示例查询非常适合以下几种使用场景:

  • 用一组静态或动态约束查询你的数据存储。
  • 频繁重构领域对象,而不必担心破坏已有查询。
  • 独立于底层数据存储 API 进行工作。

示例查询也有一些限制:

  • 不支持嵌套或分组的属性约束,例如 firstname = ?0 or (firstname = ?1 and lastname = ?2)。
  • 字符串匹配的支持取决于具体数据存储。根据数据库的不同,String 匹配可能支持开头/包含/结尾/正则等方式。
  • 其他属性类型采用精确匹配。

在开始使用示例查询之前,你需要有一个领域对象。首先,为你的仓库创建一个接口,如下例所示:

public class Person {

@Id
private String id;
private String firstname;
private String lastname;
private Address address;

// … getters and setters omitted
}

上面的示例展示了一个简单的领域对象。你可以用它来创建 Example。默认情况下,值为 null 的字段会被忽略,字符串使用数据存储特定的默认方式进行匹配。

备注

属性是否纳入示例查询的查询条件基于可空性。使用原始类型(int、double、…)的属性总会被纳入,除非 ExampleMatcher 忽略该属性路径。

可以使用 of 工厂方法,或使用 ExampleMatcher 来构建 Example。Example 是不可变的。下面的代码展示了一个简单的 Example:

示例 1. 简单 Example

Person person = new Person();                         1
person.setFirstname("Dave"); 2

Example<Person> example = Example.of(person); 3
  • 创建领域对象的新实例。

  • 设置要查询的属性。

  • 创建 Example。

你可以通过仓库来运行示例查询。为此,让你的仓库接口继承 QueryByExampleExecutor<T>。下面的代码展示了 QueryByExampleExecutor 接口的一段摘录:

public interface QueryByExampleExecutor<T> {

<S extends T> S findOne(Example<S> example);

<S extends T> Iterable<S> findAll(Example<S> example);

// … more functionality omitted.
}

Example 匹配器​

Example 并不局限于默认设置。你可以通过 ExampleMatcher 指定自己的字符串匹配、null 处理和属性特定设置的默认值,如下例所示:

示例 2. 自定义匹配的 Example 匹配器

Person person = new Person();                          1
person.setFirstname("Dave"); 2

ExampleMatcher matcher = ExampleMatcher.matching() 3
.withIgnorePaths("lastname") 4
.withIncludeNullValues() 5
.withStringMatcher(StringMatcher.ENDING); 6

Example<Person> example = Example.of(person, matcher); 7
  • 创建领域对象的新实例。

  • 设置属性。

  • 创建一个 ExampleMatcher,要求所有值都匹配。即使不做进一步配置,它在此阶段也可使用。

  • 构造一个新的 ExampleMatcher,忽略 lastname 属性路径。

  • 构造一个新的 ExampleMatcher,忽略 lastname 属性路径并纳入 null 值。

  • 构造一个新的 ExampleMatcher,忽略 lastname 属性路径、纳入 null 值,并执行后缀字符串匹配。

  • 基于领域对象和已配置的 ExampleMatcher 创建一个新的 Example。

默认情况下,ExampleMatcher 要求探测对象上设置的所有值都匹配。如果你想获取与隐式定义的任一谓词匹配的结果,请使用 ExampleMatcher.matchingAny()。

你可以为单个属性指定行为(例如 “firstname” 和 “lastname”,对于嵌套属性则是 “address.city”)。你可以通过匹配选项和大小写敏感性来调整,如下例所示:

ExampleMatcher matcher = ExampleMatcher.matching()
.withMatcher("firstname", endsWith())
.withMatcher("lastname", startsWith().ignoreCase());
}

配置匹配器选项的另一种方式是使用 lambda(Java 8 引入)。这种方式会创建一个回调,让实现者修改匹配器。你无需返回匹配器,因为配置选项保存在匹配器实例内部。下面的示例展示了一个使用 lambda 的匹配器:

ExampleMatcher matcher = ExampleMatcher.matching()
.withMatcher("firstname", match -> match.endsWith())
.withMatcher("firstname", match -> match.startsWith());
}

由 Example 创建的查询使用配置的合并视图。默认匹配设置可以在 ExampleMatcher 级别设置,而单个设置可以应用于特定的属性路径。在 ExampleMatcher 上设置的设置会被属性路径设置继承,除非属性路径中显式定义了自己的设置。属性路径上的设置优先于默认设置。下表描述了各种 ExampleMatcher 设置的作用范围:

表 1. ExampleMatcher 设置的作用范围

设置作用范围
null 处理ExampleMatcher
字符串匹配ExampleMatcher 和属性路径
忽略属性属性路径
大小写敏感性ExampleMatcher 和属性路径
值转换属性路径

流式 API​

QueryByExampleExecutor 定义了流式查询方法,通过 findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction) 基于 Example 实例灵活执行查询。

与其他方法一样,它执行从 Example 派生的查询。不过,查询函数让你能够掌控查询执行中那些无法以其他方式动态控制的方面。你可以通过调用 FetchableFluentQuery 的各种中间方法和终止方法来做到这一点。

中间方法

  • sortBy:为结果应用排序。重复调用会追加每个 Sort(注意:使用带排序的 Pageable 调用 page(Pageable) 会覆盖之前的任何排序顺序)。
  • limit:限制结果数量。
  • as:指定要读取或投影到的类型。
  • project:限制查询的属性。

终止方法

  • first、firstValue:返回第一个值。如果查询未产生任何结果,first 返回 Optional<T> 或 Optional.empty()。firstValue 是其可空变体,无需使用 Optional。
  • one、oneValue:返回唯一一个值。如果查询未产生任何结果,one 返回 Optional<T> 或 Optional.empty()。oneValue 是其可空变体,无需使用 Optional。如果找到多个匹配项,则抛出 IncorrectResultSizeDataAccessException。
  • all:将所有结果作为 List<T> 返回。
  • page(Pageable):将所有结果作为 Page<T> 返回。
  • slice(Pageable):将所有结果作为 Slice<T> 返回。
  • scroll(ScrollPosition):使用滚动(偏移量、键集)将结果作为 Window<T> 返回。
  • stream():返回一个 Stream<T> 以惰性处理结果。该流是有状态的,使用后必须关闭。
  • count 和 exists:返回匹配实体的数量,或是否存在任一匹配。
备注

中间方法和终止方法必须在查询函数内部调用。

示例 3. 使用流式 API 获取按 lastname 排序的投影 Page

Page<CustomerProjection> page = repository.findBy(example,
q -> q.as(CustomerProjection.class)
.page(PageRequest.of(0, 20, Sort.by("lastname")))
);

示例 4. 使用流式 API 获取按 lastname 排序的多个可能结果中的最后一个

Optional<Customer> match = repository.findBy(example,
q -> q.sortBy(Sort.by("lastname").descending())
.first()
);

运行 Example​

下面的示例对仓库使用示例查询:

示例 5. 通过仓库使用示例查询

interface PersonRepository extends ListQueryByExampleExecutor<Person> {
}

class PersonService {

@Autowired PersonRepository personRepository;

List<Person> findPeople(Person probe) {
return personRepository.findAll(Example.of(probe));
}
}

Redis 仓库及其二级索引支持 Spring Data 示例查询功能的一个子集。具体来说,只有精确、区分大小写且非空的值会用于构造查询。

二级索引使用基于 set 的操作(set 交集、set 并集)来确定匹配的键。向查询中添加未建索引的属性不会返回任何结果,因为不存在索引。示例查询支持会检查索引配置,仅将被索引覆盖的属性纳入查询。这是为了防止意外纳入未建索引的属性。

不区分大小写的查询和不支持的 StringMatcher 实例会在运行时被拒绝。

下面的列表展示了示例查询支持的选项:

  • 对简单属性和嵌套属性进行区分大小写的精确匹配
  • Any/All 匹配模式
  • 条件值的值转换
  • 从条件中排除 null 值

下面的列表展示了示例查询不支持的属性:

  • 不区分大小写的匹配
  • 正则、前缀/包含/后缀字符串匹配
  • 查询关联、集合和 Map 类属性
  • 从条件中纳入 null 值
  • 带排序的 findAll