Query by Example

Introduction

本章介绍了按示例查询并说明如何使用它。

按示例查询 (QBE) 是一种具有简单界面的用户友好查询技术。它允许动态创建查询，并且不要求您编写包含字段名称的查询。事实上，按示例查询根本不要求您使用特定于存储的查询语言编写查询。

本小节介绍 Query by Example 的核心概念。该信息从 Spring Data Commons 模块中提取。根据您的数据库，字符串匹配支持可能受限。

Usage

按示例查询 API 包含四个部分：

探测：带已填充字段的域对象的实际示例。
ExampleMatcher：ExampleMatcher 携带有关如何匹配特定字段的详细信息。它可以在多个示例中重用。
Example：Example 由探测和 ExampleMatcher 组成。它用于创建查询。
FetchableFluentQuery：FetchableFluentQuery 提供了一个流畅的 API，它允许进一步定制从 Example 派生的查询。使用流畅的 API 可以让你为查询指定排序投影和结果处理。

按示例查询非常适合几种用例：

通过一组静态或动态约束查询你的数据存储。
频繁重构域对象，而不用担心损坏现有查询。
独立于底层数据存储 API 运行。

按示例查询也有一些限制：

不支持嵌套或分组的属性约束，例如 firstname = ?0 or (firstname = ?1 and lastname = ?2)。
在字符串匹配方面提供特定于存储的支持。根据你的数据库，字符串匹配可以支持字符串的 starts/contains/ends/regex。
对其他属性类型进行精确匹配。

在开始使用按示例查询之前，您需要有一个域对象。要开始，请为您的存储库创建一个接口，如下例所示：

Sample Person object

public class Person {

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

  // … getters and setters omitted
}

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

将属性包含到 Query by Example 标准中基于空值能力。使用基本类型（int、double、…）的属性始终会包含，除非 <<`ExampleMatcher` 忽略属性路径，query-by-example.matchers>>。

可以通过使用 of 工厂方法或使用 [ExampleMatcher，查询 by示例。匹配器 ]. Example 是不可变的。以下清单显示了一个简单的示例：

Example 1. Simple Example

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

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

1	创建域对象的全新实例。
2	设置要查询的属性。
3	Create the `Example`.

您可以使用存储库运行示例查询。要做到这一点，让您的存储库接口扩展 QueryByExampleExecutor<T>。以下清单显示了 QueryByExampleExecutor 接口的摘录：

The 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 Matchers

示例不仅限于默认设置。您可以使用 ExampleMatcher 指定字符串匹配、null 处理和特定于属性的设置的默认值，如下例所示：

Example 2. Example matcher with customized matching

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

1	创建域对象的全新实例。
2	Set properties.
3	创建 `ExampleMatcher` 来预期匹配所有值。即使在没有进一步配置的情况下，它也可以在此阶段使用。
4	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径。
5	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径并包括空值。
6	构造一个新的 `ExampleMatcher` 来忽略 `lastname` 属性路径，以包含空值并执行后缀字符串匹配。
7	基于域对象和已配置的 `ExampleMatcher` 创建一个新的 `Example`。

默认情况下，ExampleMatcher 期望探测器上设置的所有值都匹配。如果您想要获得与隐式定义的任何谓词匹配的结果，请使用 ExampleMatcher.matchingAny()。

您可以指定单个属性（例如“firstname”和“lastname”，或对于嵌套属性，“address.city”）的行为。您可以用匹配选项和大写/小写敏感性对其进行微调，如下例所示：

Configuring matcher options

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

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

Configuring matcher options with lambdas

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

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

Table 1. Scope of `ExampleMatcher` settings
Setting	Scope
Null-handling	`ExampleMatcher`
String matching	`ExampleMatcher` and property path
Ignoring properties	Property path
Case sensitivity	`ExampleMatcher` and property path
Value transformation	Property path

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 定义了您获得什么样的结果，以及在可用结果多于预期数量时查询将如何进行。

Use the fluent API to get the last of potentially many results, ordered by lastname.

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

这是一个示例：

Unresolved include directive in modules/ROOT/pages/query-by-example.adoc - include::example$r2dbc/QueryByExampleTests.java[]

1	创建一个具有条件的域对象（将忽略 `null` 字段）。
2	使用域对象，创建一个 `Example`。
3	通过仓库，执行查询（对单个项目使用 `findOne`）。

这说明了如何使用领域对象制作一个简单的探测。在这种情况下，它将基于 Employee`对象的`name`字段等于 `Frodo 来进行查询。null 字段被忽略。

Unresolved include directive in modules/ROOT/pages/query-by-example.adoc - include::example$r2dbc/QueryByExampleTests.java[]

1	创建一个与所有字段匹配的自定义 `ExampleMatcher`（对 ANY 字段使用 `matchingAny()` 进行匹配）
2	对于 `name` 字段，使用与字段末尾匹配的通配符
3	根据 `null` 匹配列（不要忘记，`NULL` 在关系数据库中不等于 `NULL`）。
4	在形成查询时，忽略 `role` 字段。
5	将自定义 `ExampleMatcher` 插入探针中。

还可以对任何属性应用 withTransform()，允许你在形成查询之前转换一个属性。例如，可以在创建查询之前对基于 String 的属性应用 toUpperCase()。

当你事先不知道查询中所需的所有字段时，按示例查询非常有用。如果要在用户可以选择字段的网页上构建一个筛选器，那么按示例查询是一种灵活地将它捕获到一个高效查询中的不错方式。