
# 派生クエリ

派生クエリとは、名前がクエリになっているリポジトリのメソッドです。`findByTitleContainingIgnoreCase(String text)` は、タイトルに `text` を (大文字小文字を無視して) 含む本を読み込みます。ビルドは名前を解析し、エンティティと照合し、そのための定数のクエリツリーを書きます。同じメソッドが、メモリ上、SQLite、PostgreSQL のどのストアでも動きます。

## 使う理由

ほとんどのファインダーは、いくつかの列に対する単純な条件です。そのそれぞれに SQL を書くのは雑音で、文字列の中の SQL は実行時にしかチェックされません。メソッド名は短く、問いのように読め、ビルドがチェックします。`findByTitel` は本番での失敗ではなく、`did you mean 'title'?` 付きのビルドエラーになります。

## 例

```dart
abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  Future<List<Book>> findByTitle(String title);
  Future<List<Book>> findByTitleContainingIgnoreCase(String part);
  Future<List<Book>> findByTitleAndYear(String title, int year);
  Future<List<Book>> findByYearBetween(int from, int to);
  Future<List<Book>> findByYearIn(List<int> years);
  Future<List<Book>> findBySubtitleIsNull();
  Future<List<Book>> findByInStockTrue();

  Future<Book?> findOneByTitle(String title);       // なければ null
  Future<Book> getByTitle(String title);            // なければ EmptyResultDataAccessException
  Future<Book?> findFirstByOrderByYearAsc();        // 最も古いもの
  Future<List<Book>> findTop2ByOrderByYearDesc();   // 最も新しい 2 冊
  Future<List<Book>> findByInStockOrderByYearDescTitleAsc(bool inStock);
  Stream<Book> streamByInStock(bool inStock);       // 届くそばからの行

  Future<int> countByInStock(bool inStock);
  Future<bool> existsByTitle(String title);
  Future<int> deleteByYearLessThan(int year);       // 削除した数
  Future<void> removeByTitle(String title);
  Future<List<Book>> deleteByInStock(bool inStock); // 削除した集約
}
```

## 名前の構成

`findTop5ByTitleContainingIgnoreCaseAndYearGreaterThanOrderByYearDesc` は次のように読みます。

| 部分 | ここでは | 意味 |
|---|---|---|
| サブジェクト | `find` | 一致したものをどうするか。 |
| 上限 | `Top5` | 最大 5 件 (`First` だけなら 1 件)。 |
| `By` | `By` | 条件の始まり。 |
| 条件 | `TitleContainingIgnoreCase` | プロパティ、演算子、場合により `IgnoreCase`。 |
| `And` / `Or` | `And` | 条件をつなぐ。`And` は `Or` より強く結び付く。 |
| 条件 | `YearGreaterThan` | |
| 順序 | `OrderByYearDesc` | 結果の順序。 |

## サブジェクト

| プレフィックス | 働き | 戻り値 |
|---|---|---|
| `find`、`read`、`get`、`query`、`search`、`stream` | 一致したものを読み込む。 | `List`、`Iterable`、`Set`、`Stream`、`Page`、`Slice`、または一つのエンティティ |
| `watch` | 一致したものを読み込み、最新に保つ。変更を報告するストアで使える。[行の変更](changes.md) を参照。 | `Stream<List<Book>>` |
| `changes` | 条件に一致する行の変更。同じく、そのようなストアで。 | `Stream<RowChange<Book>>` |
| `count` | 一致したものを数える。 | `Future<int>` |
| `exists` | 一致するものがあるかどうか。 | `Future<bool>` |
| `delete`、`remove` | 一致したものを子とともに削除する。 | `Future<int>` (件数)、`Future<void>`、または削除した集約 (`Future<List<Book>>`) |

プレフィックスの後の `Distinct` (`findDistinctByInStock`) は重複を取り除きます。`Top<n>` と `First<n>` は結果を制限します。`Pageable` がある場合、ページの範囲はその上限で切られます (ページサイズ 2 の `findTop3By...(Pageable)` は 2 件と 1 件のページになります)。`By` の後に何もない `findAll...` と `countBy` は、すべての集約に一致します。

## 演算子

| キーワード (と別名) | パラメーター | 条件 |
|---|---|---|
| (なし)、`Is`、`Equals` | 1 | `= value` |
| `Not`、`IsNot` | 1 | `<> value` |
| `Between`、`IsBetween` | 2 | `between from and to` |
| `LessThan`、`IsLessThan`、`Before`、`IsBefore` | 1 | `< value` |
| `LessThanEqual`、`IsLessThanEqual` | 1 | `<= value` |
| `GreaterThan`、`IsGreaterThan`、`After`、`IsAfter` | 1 | `> value` |
| `GreaterThanEqual`、`IsGreaterThanEqual` | 1 | `>= value` |
| `IsNull`、`Null` | 0 | `is null` |
| `IsNotNull`、`NotNull` | 0 | `is not null` |
| `Like`、`IsLike` | 1 | `like value` (自分のパターン) |
| `NotLike`、`IsNotLike` | 1 | `not like value` |
| `StartingWith`、`IsStartingWith`、`StartsWith` | 1 | `like 'value%'` |
| `EndingWith`、`IsEndingWith`、`EndsWith` | 1 | `like '%value'` |
| `Containing`、`IsContaining`、`Contains` | 1 | `like '%value%'` |
| `NotContaining`、`IsNotContaining`、`NotContains` | 1 | `not like '%value%'` |
| `In`、`IsIn` | 1 (コレクション) | `in (...)` |
| `NotIn`、`IsNotIn` | 1 (コレクション) | `not in (...)` |
| `True`、`IsTrue` | 0 | `= true` |
| `False`、`IsFalse` | 0 | `= false` |

条件の後の `IgnoreCase` は小文字で比較し、末尾の `AllIgnoreCase` はそれをすべての条件に適用します。パラメーターは条件の順に続き、その後に任意で `Sort` か `Pageable` が続きます。

## テキストである値

- `StartingWith`、`EndingWith`、`Containing` では、引数はパターンではなくテキストです。その中の `%`、`_`、`\` は、どのストアでもスターターがエスケープします。`Like` では、パターンは自分のものです。
- テキストの引数の中の NUL 文字 (`\u0000`) は、何かが送られる前に拒否されます。どのストアでも `InvalidDataArgumentException` (`InvalidDataAccessApiUsageException` の一種) です。PostgreSQL はそれを保持できず、SQLite の `LIKE` はそこで読むのをやめるためです。
- `IgnoreCase` は ASCII だけでなく、すべての文字を畳み込みます。SQLite では、ドライバーが Dart の `toLowerCase` を使う `lower` を登録するため、メモリ上のストアと同じく `ДЮНА` は `дюна` に一致します。PostgreSQL では `lower()` で、データベースのロケールが知っているものを畳み込みます。

## 長い In のリスト

PostgreSQL では、派生の `In` や `NotIn` はリストを一つの配列パラメーターとしてバインドする (`= any($1)`、`<> all($1)`) ため、どの長さでも動きます。SQLite は要素ごとに一つの値をバインドし、一つの文に 32 766 個の値まで許します。それより長いリストは、その旨を示す `InvalidDataArgumentException` です。リストの中の `null` は、`In` では無視され、`NotIn` では SQL と同じく何にも一致しなくなります。

## 一つの結果

| 戻り値の型 | 一致なし | 複数一致 |
|---|---|---|
| `Future<Book?>` | `null` | `IncorrectResultSizeDataAccessException` |
| `Future<Book>` | `EmptyResultDataAccessException` | `IncorrectResultSizeDataAccessException` |

`First` や `Top` では、複数の一致はエラーではなく、最初のものが取られます。

## 順序

`OrderBy` は一つ以上のプロパティを、それぞれ `Asc` (デフォルト) または `Desc` とともに指定します: `OrderByYearDescTitleAsc`。`Sort` や `Pageable` のパラメーターは、名前の順序の後にその順序を追加します。[ページングとソート](paging-and-sorting.md) を参照してください。

## トランザクションとロック

- `deleteBy` はリポジトリのストアのトランザクションの中で実行され、呼び出し元のものがあればそれに参加します。
- `@Lock` を付けたファインダーは、読んだ行をトランザクションが終わるまでロックします ([ロック](locks.md) を参照)。

## ビルドがチェックするもの

- 各プロパティがエンティティに存在し、保存されること (`@Transient` でないこと)。綴りが間違っていれば候補付き。
- パラメーターの数が条件と一致すること。`Pageable` や `Sort` は最後に来ること。
- 参照はそれ自身の型で比較されること: `findByEditor(AggregateReference<Editor, int>)`、または `@Reference` プロパティなら `findByAuthorId(int)`。

Zed 拡張機能 `dart_spring` では、言語サーバーが入力中に同じ文法で名前を読みます。不明なプロパティに候補付きで下線を引き、パラメーターの数をチェックし、ホバーで名前が表す SQL を示します。

## Spring (Java) との対応

```java
List<Book> findByTitleContainingIgnoreCase(String part);
Optional<Book> findFirstByOrderByYearAsc();
long countByInStock(boolean inStock);
```

文法とキーワードは Spring Data のものです。結果は `Future` か `Stream` で、一つの結果は `Optional` ではなく nullable で、名前は起動時ではなくビルドがチェックします。

## 関連項目

- [リポジトリ](repositories.md)
- [ページングとソート](paging-and-sorting.md)
- [@Query](query.md)
