派生クエリ

派生クエリとは、名前がクエリになっているリポジトリのメソッドです。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 が続きます。

テキストである値

長い 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 のパラメーターは、名前の順序の後にその順序を追加します。ページングとソート を参照してください。

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

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

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

Spring (Java) との対応

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

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

関連項目