Running an Example

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()
);

Running an Example

以下示例对存储库使用按示例查询：

Example 3. Query by Example using a Repository
interface PersonRepository extends QueryByExampleExecutor<Person> {
}

class PersonService {

  @Autowired PersonRepository personRepository;

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

Redis 存储库支持，并通过其辅助索引支持 Spring Data 按示例查询功能的一个子集。尤其是，仅使用精确的、区分大小写的和非空值来构建查询。

辅助索引使用基于集合的操作（集合交集、集合并集）来确定匹配键。将未编入索引的属性添加到查询中不会返回任何结果，因为不存在索引。按示例查询支持检查索引配置，以仅将索引覆盖的属性包括在查询中。这样做是为了防止意外包括未编入索引的属性。

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

以下列表显示了受支持的按示例查询选项：

  • 对大小写敏感，精确匹配简单和嵌套属性

  • Any/All match modes

  • 转换条件值

  • 排除条件中的 null 值

以下列表显示了不受按示例查询支持的属性：

  • Case-insensitive matching

  • Regex, prefix/contains/suffix String-matching

  • 查询关联、集合和地图样属性

  • 包括条件中的 null 值

  • findAll with sorting