派生クエリ
派生クエリとは、名前がクエリになっているリポジトリのメソッドです。findByTitleContainingIgnoreCase(String text) は、タイトルに text を (大文字小文字を無視して) 含む本を読み込みます。ビルドは名前を解析し、エンティティと照合し、そのための定数のクエリツリーを書きます。同じメソッドが、メモリ上、SQLite、PostgreSQL のどのストアでも動きます。
使う理由
ほとんどのファインダーは、いくつかの列に対する単純な条件です。そのそれぞれに SQL を書くのは雑音で、文字列の中の SQL は実行時にしかチェックされません。メソッド名は短く、問いのように読め、ビルドがチェックします。findByTitel は本番での失敗ではなく、did you mean 'title'? 付きのビルドエラーになります。
例
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 |
一致したものを読み込み、最新に保つ。変更を報告するストアで使える。行の変更 を参照。 | 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 のパラメーターは、名前の順序の後にその順序を追加します。ページングとソート を参照してください。
トランザクションとロック
deleteByはリポジトリのストアのトランザクションの中で実行され、呼び出し元のものがあればそれに参加します。@Lockを付けたファインダーは、読んだ行をトランザクションが終わるまでロックします (ロック を参照)。
ビルドがチェックするもの
- 各プロパティがエンティティに存在し、保存されること (
@Transientでないこと)。綴りが間違っていれば候補付き。 - パラメーターの数が条件と一致すること。
PageableやSortは最後に来ること。 - 参照はそれ自身の型で比較されること:
findByEditor(AggregateReference<Editor, int>)、または@ReferenceプロパティならfindByAuthorId(int)。
Zed 拡張機能 dart_spring では、言語サーバーが入力中に同じ文法で名前を読みます。不明なプロパティに候補付きで下線を引き、パラメーターの数をチェックし、ホバーで名前が表す SQL を示します。
Spring (Java) との対応
List<Book> findByTitleContainingIgnoreCase(String part);
Optional<Book> findFirstByOrderByYearAsc();
long countByInStock(boolean inStock);
文法とキーワードは Spring Data のものです。結果は Future か Stream で、一つの結果は Optional ではなく nullable で、名前は起動時ではなくビルドがチェックします。