Scrolling

滚动是迭代处理较大结果集区块的一种更细粒度的处理方式。滚动包含稳定的排序、滚动类型（基于偏移或基于键集的滚动）以及结果限制。你可以使用属性名称定义简单的排序表达式，并使用 xref:repositories/query-methods-details.adoc#repositories.limit-query-result[Top 或 First 关键字通过查询派生定义静态结果限制。你可以联接表达式以将多个条件收集到一个表达式中。滚动查询返回一个 Window<T>，它允许获取滚动位置以继续获取下一个 Window<T> 直到您的应用程序使用整个查询结果。类似于通过获取下一批结果使用 Java Iterator<List<…>> 消费查询结果，查询结果滚动允许您通过 Window.positionAt(…) 访问 ScrollPosition。

Window<User> users = repository.findFirst10ByLastnameOrderByFirstname("Doe", ScrollPosition.offset());
do {

  for (User u : users) {
    // consume the user
  }

  // obtain the next Scroll
  users = repository.findFirst10ByLastnameOrderByFirstname("Doe", users.positionAt(users.size() - 1));
} while (!users.isEmpty() && users.hasNext());

WindowIterator 提供了一个实用工具，可通过消除检查是否存在下一个 Window 和应用 ScrollPosition 的需求来简化跨 Window 的滚动。

WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
  .startingAt(OffsetScrollPosition.initial());

while (users.hasNext()) {
  User u = users.next();
  // consume the user
}

Scrolling using Offset

偏移量滚动类似于分页，它使用偏移量计数器跳过一定数目的结果，并让数据源仅从给定偏移量开始返回结果。此简单机制可避免向客户端应用程序发送较大的结果。但是，在服务器返回结果之前，大多数数据库都需要实现完整的查询结果。

Example 1. Using OffsetScrollPosition with Repository Query Methods

interface UserRepository extends Repository<User, Long> {

  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, OffsetScrollPosition position);
}

WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
  .startingAt(OffsetScrollPosition.initial()); 1

1	从位置 `0` 上的起始偏移量开始。

Scrolling using Keyset-Filtering

基于偏移量的方法需要大多数数据库在服务器返回结果之前实现全部结果的物化。因此，当客户端只看到请求结果的一部分时，服务器需要构建全部结果，这会导致额外的负载。

键集过滤方法通过利用数据库的内置功能来检索结果子集，旨在降低单个查询的计算和 I/O 需求。此方法维护一组键用于通过查询中传入键来恢复滚动，有效修正筛选条件。

键集过滤的核心思想是使用稳定的排序顺序开始检索结果。一旦想要滚动到下一个块，就可以获取用于重建排序结果中位置的 ScrollPosition 。ScrollPosition 捕获当前 Window 中最后一个实体的键集。要运行查询，重建会重写条件子句以包括所有排序字段和主键，以便数据库可以利用潜在的索引来运行查询。数据库只需要根据给定的键集位置构建一个更小的结果，而无需完全实现一个较大的结果，然后跳过一些结果直到达到特定的偏移量。

键集过滤需要键集属性（用于排序的属性）为非空。此限制适用于由于比较运算符对存储特定的 null 值处理以及由于需要针对索引来源运行查询。针对空属性的键集过滤会导致意外的结果。

Using KeysetScrollPosition with Repository Query Methods

interface UserRepository extends Repository<User, Long> {

  Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, KeysetScrollPosition position);
}

WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
  .startingAt(ScrollPosition.keyset()); 1

1	从一开始开始，不使用其他筛选条件。

当数据库包含与排序字段相匹配的索引时，键集过滤效果最佳，因此静态排序效果很好。应用键集过滤的滚动查询需要将排序顺序中使用的属性通过查询返回，而这些属性必须映射在返回的实体中。

可以使用接口和 DTO 投影，但是确保包括已对其进行排序的所有属性，以避免键集提取失败。

在指定 Sort 顺序时，包含与查询相关的排序属性就足够了；如果您不想确保唯一查询结果，就不需要这样做。键集查询机制会通过包括主键（或复合主键的任何剩余部分）来修正排序顺序，确保每个查询结果都是唯一的。