
# ページングとソート

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

## 使う理由

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

## 例

```dart
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 アプリケーションで](web.md) を参照)。
- **ソートのプロパティを許可リストにしてください。** ソートは `ORDER BY` のオラクルです。クライアントは、パスワードのハッシュのように、読めない値の順序を知ることができます。

## Spring (Java) との対応

```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` は異なります。

## 関連項目

- [派生クエリ](derived-queries.md)
- [@Query](query.md)
- [Web アプリケーションで](web.md)
