@Query

@Query('...') は、リポジトリのメソッドに、名前から派生するクエリの代わりに独自の SQL を与えます。パラメーターは名前付き (:year) で、メソッドのパラメーターに名前でバインドされます。値は常にバインドされ、テキストに書き込まれることは決してありません。ビルドがメソッド、テキスト、パラメーター、SpEL 式をチェックするため、ほとんどの誤りはビルドエラーになります。

使う理由

派生クエリは単純な条件をカバーします。結合、集約関数、レポート、一括更新には SQL が必要です。Spring では、その SQL はリポジトリが作られるとき、つまり起動時にしかチェックされません。ここではビルドがエンティティとマイグレーションを知っており、何かが動く前にテキストをチェックします。綴りを間違えた列は、候補付きのビルドエラーになります。

例

class BookCard {
  BookCard({required this.title, required this.authorName});

  final String title;
  final String authorName;   // 列 author_name から埋められる
}

abstract interface class BookRepository implements ListCrudRepository<Book, int> {
  // {Book} はエンティティの引用符付きのテーブル、{Book.authorId} はそのプロパティの列。
  @Query('select {Book.title} from {Book} where {Book.authorId} = :authorId')
  Future<List<String>> titlesOf(int authorId);

  // 行を自分のクラスに。件数の文付きでページングする。
  @Query(
    'select b.title, a.name as author_name from books b '
    'join authors a on a.id = b.author_id where b.year > :year',
    countQuery: 'select count(*) from books where year > :year',
  )
  Future<Page<BookCard>> cards(int year, Pageable page);

  // 変更: 変更された行の数を返す。
  @Modifying()
  @Query('update books set year = year + 1 where year > :year')
  Future<int> shift(int year);

  // 引数からの SpEL の値。ビルドが Dart にコンパイルする。
  @Query('select * from books where title = :#{#book.title}')
  Future<List<Book>> sameTitle(Book book);

  // デフォルト付きの Environment のプロパティ。
  @Query(r'select * from books order by year desc limit ${shop.top-size:10}')
  Future<List<Book>> top();

  // コレクションのパラメーターは、値ごとに一つのマーカーに展開される。
  @Query('select * from books where id in (:ids)')
  Future<List<Book>> some(List<int> ids);
}

属性

属性 意味
value メソッドの SQL。
countQuery Page を返すメソッドのための、すべての結果を数える SQL。
rowMapper 各行をマッピングする T Function(JdbcRow row)。定数として与える static メソッドかトップレベル関数。メソッドは T の List、Set、Stream、Page、Slice、または一つの T を返す。
resultSetExtractor 行をまたぐ結果 (一対多) のために、結果全体をメソッドが返すものに変える R Function(JdbcResult result)。rowMapper とは併用できず、Pageable も使えない。
name 名前付きクエリのために予約されている。まだ対応していない (ビルドエラー)。
@Query(
  'select a.id, a.name, b.title from authors a join books b on b.author_id = a.id',
  resultSetExtractor: AuthorWithBooks.extract,
)
Future<List<AuthorWithBooks>> authorsWithBooks();

テキストに書くもの

書くもの なるもの
:name メソッドのパラメーター name。値としてバインドされる。コレクションは要素ごとに一つのマーカーになる。
{Book} マッピング (命名戦略、@Table) を通した、エンティティ Book の引用符付きのテーブル。
{Book.authorId} プロパティ authorId の引用符付きの列 (author_id)。修飾されないため、結合では b.{Book.authorId} と書く。
:#{expression} パラメーターとしてバインドされる SpEL の値。
#{#entityName} リポジトリのエンティティの引用符付きのテーブル。
${key:default} Environment のプロパティ。起動時に解決され、テキストに書き込まれる。

単なる ? とその他の #{...} は拒否されます。名前付きパラメーターを使ってください。

結果

行は、その型に応じて、メソッドが返すものになります。

戻り値の型 行がなるもの
エンティティ そのテーブルの列からのエンティティ。子も読み込まれる。
アプリケーションのクラス そのインスタンス: 列は名前で、author_name は authorName に。ジェネレーターがクラスを記述する。
int、String、列の型 唯一の列。
Map<String, Object?> 行ごとに一つのマップ。
rowMapper または resultSetExtractor を伴う任意のもの 関数が返すもの。

それぞれを Future<List<T>>、Future<Set<T>>、Future<T?>、Future<T>、Stream<T>、Future<Page<T>>、Future<Slice<T>> で返します。Page や Slice には Pageable のパラメーターが必要で、Sort や Pageable のパラメーターはテキストにその順序を追加します。

@Modifying

データを変更するクエリ (update、delete、insert) には @Modifying() が必要です。メソッドは次のものを返します。

@Modifying メソッドには rowMapper も Pageable もありません。@Modifying のない void メソッドはビルドエラーです。@Modifying のクエリは save を通らないことを忘れないでください。@Version のチェックも、監査もありません。

SpEL の値

:#{...} の値は、ビルドにできる場合は、引数の関数として Dart で書かれます。

@Query('select * from books where title = :#{#book.title}')
Future<List<Book>> sameTitle(Book book);
// 生成されたもの: expressions: [(arguments, context) => (arguments[0] as Book).title]

そのため誤りは候補付きのビルドエラーになり、実行時に解釈されるものは何もありません。

BookRepository.sameTitle: the expression :#{#book.titel} is invalid:
  No property 'titel' on type 'Book'; did you mean 'title'?
式の中で 意味
#name メソッドのパラメーター name。
#p0、#a0 最初の引数。
#root 引数のリスト。
#entityName エンティティの引用符付きのテーブル。
#methodName メソッドの名前。
@clock clock という名前の Bean。
@environment.getProperty('key', 'default') プロパティ。

不明な #variable、誤った呼び出し、?. なしでの null になりうる値のメンバー、構文エラーはビルドエラーです。コンパイラーが手を付けないもの (T(...)、new、選択と射影、matches、instanceof、Java 風の size()、Object のメンバーや知らない Bean のメンバー) は実行時に解釈され、そのためにはそのメソッドの引数のクラスだけが記述されます。クラスに @Introspected() を付ければ、常にそれが記述されます。SpEL を参照してください。

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

インターフェースの問題はそれぞれ一つのビルドエラーになり、他のものと一緒に示されます。

Invalid repository BookRepository:
  - BookRepository.cards: b.titel: no column titel in books, did you mean 'title'?

ビルドは、エンティティのテーブルと列、そして lib/resources/ のマイグレーションと初期化スクリプトのテーブルと列を知っています。db/migration/V*__*.sql、R__*.sql、schema.sql で、create table、alter table (列の追加、名前の変更、削除、テーブルの名前の変更)、drop table、その select リストを伴う create view を、実行される順に読みます。

このルールは、確信がないときは何も言いません。

起動時

実行時に依存するものは、リポジトリが作られるときにチェックされ、すべての問題が一つのエラーに列挙されます。

エディターで

dart_spring 拡張機能 (Zed) の言語サーバーはデータ層を知っています。@Query('...') の中では、SQL に色を付け、{ (エンティティ)、{Book. (プロパティ)、: (パラメーター) を補完し、{Book} からクラスへ、:year からパラメーターへ移動し、ホバーでテーブルと列を示し、ビルドが報告するものを入力中に報告し、さらにクエリが一度も使わないパラメーターに警告を出します。

Spring (Java) との対応

@Query("select * from books where author_id = :authorId")
List<Book> byAuthor(@Param("authorId") long authorId);

@Modifying
@Query("update books set year = year + 1 where year > :year")
int shift(int year);

パラメーターは @Param なしで名前で照合されます。{Entity} と {Entity.property} のプレースホルダーは追加されたものです。rowMapperClass と resultSetExtractorClass は、関数として与える rowMapper と resultSetExtractor です。Spring はリポジトリが作られるときにテキストをチェックしますが、ここではビルドがチェックします。

関連項目