按示例查询

DeepSeek V3 中英对照 Query by Example

简介

本章介绍了 Query by Example，并解释了如何使用它。

示例查询（Query by Example，QBE）是一种用户友好的查询技术，具有简单的界面。它允许动态创建查询，并且不需要您编写包含字段名称的查询。实际上，示例查询完全不需要您使用特定存储的查询语言来编写查询。

备注

本章节解释了按示例查询（Query by Example）的核心概念。这些信息来源于 Spring Data Commons 模块。根据你使用的数据库，字符串匹配支持可能会有所限制。

用法

查询示例（Query by Example）API 包含四个部分：

• Probe（探针）：一个填充了字段的领域对象实际示例。

• ExampleMatcher（示例匹配器）：ExampleMatcher 包含了如何匹配特定字段的详细信息。它可以在多个示例中重复使用。

• Example（示例）：Example 由探针和 ExampleMatcher 组成。它用于创建查询。

• FetchableFluentQuery（可获取的流式查询）：FetchableFluentQuery 提供了一个流式 API，允许进一步定制从 Example 派生的查询。使用流式 API 可以指定查询的排序、投影和结果处理。

Query by Example 适用于以下几种使用场景：

• 使用一组静态或动态约束查询您的数据存储。

• 频繁重构领域对象，而无需担心破坏现有查询。

• 独立于底层数据存储 API 工作。

示例查询（Query by Example）也有一些局限性：

• 不支持嵌套或分组的属性约束，例如 firstname = ?0 或 (firstname = ?1 且 lastname = ?2)。

• 字符串匹配的存储特定支持。根据您的数据库，字符串匹配可以支持字符串的开头/包含/结尾/正则表达式匹配。

• 其他属性类型的精确匹配。

在开始使用 Query by Example 之前，你需要有一个领域对象。首先，为你的仓库创建一个接口，如下例所示：

public class Person {

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

  // … getters and setters omitted
}

java

前面的示例展示了一个简单的领域对象。您可以使用它来创建一个 Example。默认情况下，包含 null 值的字段会被忽略，字符串会使用存储特定的默认值进行匹配。

备注

在“按示例查询”标准中包含属性的依据是可空性。使用基本类型（如 int、double 等）的属性始终被包含，除非 ExampleMatcher 忽略了该属性路径。

可以通过使用 of 工厂方法或使用 ExampleMatcher 来构建示例。Example 是不可变的。以下清单展示了一个简单的示例：

示例 1. 简单示例

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

Example<Person> example = Example.of(person);         3

java

• 创建域对象的新实例。

• 设置要查询的属性。

• 创建 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.
}

java

示例匹配器

示例不仅限于默认设置。你可以通过使用 ExampleMatcher 来指定自己的默认值，用于字符串匹配、空值处理以及特定属性的设置，如下例所示：

示例 2. 带有自定义匹配的示例匹配器

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

java

• 创建一个新的领域对象实例。

• 设置属性。

• 创建一个 ExampleMatcher，期望所有值都匹配。即使没有进一步配置，它在此阶段也可用。

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

• 构造一个新的 ExampleMatcher，忽略 lastname 属性路径并包含空值。

• 构造一个新的 ExampleMatcher，忽略 lastname 属性路径，包含空值，并执行后缀字符串匹配。

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

默认情况下，ExampleMatcher 期望探针（probe）上设置的所有值都匹配。如果你想获取匹配任意隐式定义的谓词的结果，可以使用 ExampleMatcher.matchingAny()。

你可以为单个属性（例如 "firstname" 和 "lastname"，或者对于嵌套属性，如 "address.city"）指定行为。你可以通过匹配选项和大小写敏感性来调整它，如下例所示：

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

java

另一种配置匹配器选项的方法是使用 lambda 表达式（在 Java 8 中引入）。这种方法创建了一个回调，要求实现者修改匹配器。你不需要返回匹配器，因为配置选项保存在匹配器实例中。以下示例展示了一个使用 lambda 表达式的匹配器：

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

java

由 Example 创建的查询使用配置的合并视图。默认的匹配设置可以在 ExampleMatcher 级别进行设置，而个别设置可以应用于特定的属性路径。除非显式定义，否则 ExampleMatcher 上的设置会被属性路径设置继承。属性路径上的设置比默认设置具有更高的优先级。下表描述了各种 ExampleMatcher 设置的范围：

表 1. ExampleMatcher 设置的范围

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

Fluent API

QueryByExampleExecutor 还提供了一个我们之前未提及的方法：<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)。与其他方法一样，它执行从 Example 派生的查询。然而，通过第二个参数，你可以控制查询执行的某些方面，这些方面在其他情况下无法动态控制。你可以通过调用第二个参数中 FetchableFluentQuery 的各种方法来实现这一点。sortBy 允许你为结果指定排序方式。as 允许你指定希望将结果转换成的类型。project 限制查询的属性。first、firstValue、one、oneValue、all、page、stream、count 和 exists 定义了返回结果的类型以及当结果超出预期数量时查询的行为。

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

java

运行示例

以下示例使用查询示例（Query by Example）对存储库进行查询：

示例 3. 使用存储库进行示例查询

interface PersonRepository extends ListQueryByExampleExecutor<Person> {
}

class PersonService {

  @Autowired PersonRepository personRepository;

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

java

Redis Repositories 支持其二级索引，提供了 Spring Data 的 Query by Example 功能的一个子集。具体来说，只有精确的、区分大小写的且非空的值会被用于构建查询。

二级索引使用基于集合的操作（集合交集、集合并集）来确定匹配的键。在查询中添加一个未索引的属性将不会返回任何结果，因为该属性没有索引。Query by Example 支持会检查索引配置，以确保查询中仅包含被索引覆盖的属性。这是为了防止意外包含未索引的属性。

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

以下列表展示了支持的按示例查询（Query by Example）选项：

• 对简单属性和嵌套属性进行区分大小写的精确匹配

• 支持任意/所有匹配模式

• 对条件值进行值转换

• 从条件中排除 null 值

以下列表展示了 Query by Example 不支持的属性：

• 大小写不敏感匹配

• 正则表达式、前缀/包含/后缀字符串匹配

• 查询关联、集合和类 Map 属性

• 包含条件中的 null 值

• 带有排序的 findAll