ページングとソート

Pageable は結果の一つの範囲 (ページ番号、ページサイズ、順序) を求め、Sort は順序だけを求めます。どちらかを派生クエリや @Query メソッドの最後のパラメーターとして渡すか、findAllSorted と findAllPaged を呼びます。Page の答えは合計を知っており、Slice は次のページがあるかどうかだけを知っています。

使う理由

一覧画面や API がテーブル全体を読み込むことはありません。ユーザーが選んだ順序で 20 行を読み込み、さらにあるかどうかを知る必要があります。すべてのファインダーに LIMIT、OFFSET、ORDER BY、件数を手で書くのは繰り返しが多く間違えやすく、リクエストから取った順序を SQL に貼り付けるとインジェクションの危険があります。Pageable と Sort を使えば、そのすべてをストアが書き、ソートのプロパティはエンティティと照合されます。

例

abstract interface class BookRepository
    implements
        ListCrudRepository<Book, int>,
        ListPagingAndSortingRepository<Book, int> {
  Future<Page<Book>> findByYearAfter(int year, Pageable pageable);
  Future<Slice<Book>> findByInStockIsTrue(Pageable pageable);
  Future<List<Book>> findByInStock(bool inStock, Sort sort);
}

// ページ 0、1 ページ 20 件、新しい順、次にタイトル順。
final request = PageRequest.of(
  0,
  20,
  Sort.byOrders([const SortOrder.desc('year'), const SortOrder.asc('title')]),
);

final page = await books.findByYearAfter(1950, request);
print('${page.numberOfElements} of ${page.totalElements}, page ${page.number + 1} of ${page.totalPages}');

if (page.hasNext) {
  final next = await books.findByYearAfter(1950, page.nextPageable());
}

final all = await books.findAllSorted(Sort.by(['title']));
final first = await books.findAllPaged(PageRequest.of(0, 10));

Pageable と PageRequest

メンバー 意味
PageRequest.of(page, size, [sort]) sort で並べた、size 件のページ page (0 から)。
Pageable.unpaged([sort]) すべての結果。ソートされることもある。
pageNumber、pageSize、offset、sort リクエスト (ページなしのリクエストには番号、サイズ、オフセットがない)。
next()、previousOrFirst()、first()、withPage(n)、hasPrevious 他のページ。

PageRequest.of は、負のページ、1 未満のサイズ、オフセットが 2^53 - 1 を超えるページとサイズの組を拒否します。InvalidPagingRequestException (ArgumentError の一種) です。そのためオフセットが一周して別のページになることはありません。負のオフセットを持つ独自の Pageable は、ストアが拒否します。

Sort と SortOrder

メンバー 意味
Sort.by(['title', 'year']) 各プロパティの昇順で、順に。
Sort.byOrders([SortOrder.desc('year'), ...]) 指定したとおりの各順序。
Sort.unsorted 順序なし。
sort.and(other)、descending()、ascending() 組み合わせる、または反転する。
SortOrder.asc(p)、SortOrder.desc(p)、SortOrder(p, direction:) 一つのステップ。
order.ignoringCase() 小文字で比較する。
order.withNullHandling(NullHandling.nullsLast) native (ストアの選択)、nullsFirst、nullsLast。
Direction.fromString('desc') asc または desc。大文字小文字は無視される。

ここではソートのステップは SortOrder で、Spring の Sort.Order に当たります。@Order は Bean を並べるものだからです。

Page と Slice

メンバー Slice Page
content、hasContent、numberOfElements あり あり
number、size、sort あり あり
isFirst、isLast、hasNext、hasPrevious あり あり
nextPageable()、previousPageable() あり あり
map((item) => ...) あり あり
totalElements、totalPages なし あり

結果の順序

順序は、まず名前の OrderBy、次に Sort または Pageable のソートです。順序がなければ、ストアの順序は保証されません。テーブルをページングするのは、ソートがある場合だけにしてください。

リクエストからの入力

リクエストのパラメーターから作った Sort や Pageable が、テキストとして SQL に届くことは決してありません。

2 つのルールは利用者に残ります。それを知っているのは利用者だけだからです。

Spring (Java) との対応

Page<Book> findByYearAfter(int year, Pageable pageable);

PageRequest.of(0, 20, Sort.by(Sort.Order.desc("year"), Sort.Order.asc("title")));
repository.findAll(Sort.by("title"));

名前は Spring Data のものですが、SortOrder (Spring の Sort.Order)、findAllSorted と findAllPaged (Spring のオーバーロードされた findAll)、そしてリストを受け取る Sort.by は異なります。

関連項目