ページングとソート
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 |
なし | あり |
Pageは 2 つ目のクエリ、つまり件数を実行します。Pageを返す@Queryメソッドには、その件数の文をcountQueryで指定してください。Sliceは、次のページがあるかを知るためにページサイズより 1 行多く読み、件数は実行しません。大きなテーブルの「さらに読み込む」一覧には、こちらを選んでください。Page.empty([pageable])は空のページです。
結果の順序
順序は、まず名前の OrderBy、次に Sort または Pageable のソートです。順序がなければ、ストアの順序は保証されません。テーブルをページングするのは、ソートがある場合だけにしてください。
リクエストからの入力
リクエストのパラメーターから作った Sort や Pageable が、テキストとして SQL に届くことは決してありません。
- ソートのプロパティはエンティティのプロパティで、その列として書かれます。
@Queryでは、引用符で囲んだ識別子 (a.b) です。 - 方向は
ascとdescだけです。 - エンティティを返す
@Queryは、名前をエンティティのプロパティと列に対してチェックし、クラスを返すものは、そのクラスのプロパティ (authorNameはauthor_nameでソートする) とエンティティのものに対してチェックします。 - 存在しないプロパティは
PropertyReferenceExceptionで、そのメッセージは名前をエスケープして書くため、改行を含む名前でログの行を偽造することはできません。
2 つのルールは利用者に残ります。それを知っているのは利用者だけだからです。
- サイズに上限を設けてください。
size=1000000000を送るクライアントはテーブル全体を得ます。Web との連携はspring.data.web.pageable.max-page-sizeで上限を設けます (Web アプリケーションで を参照)。 - ソートのプロパティを許可リストにしてください。 ソートは
ORDER BYのオラクルです。クライアントは、パスワードのハッシュのように、読めない値の順序を知ることができます。
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 は異なります。