
# @Query

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

## 使う理由

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

## 例

```dart
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` | 名前付きクエリのために予約されている。まだ対応していない (ビルドエラー)。 |

```dart
@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()` が必要です。メソッドは次のものを返します。

- `Future<int>`: 変更された行の数。
- `Future<bool>`: 何らかの行が変更されたかどうか。
- `Future<void>`: 何も返さない。

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

## SpEL の値

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

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

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

```text
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](../spring-core-dart/spel/index.md) を参照してください。

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

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

- **メソッドとそのアノテーション:** `Future` か `Stream` を返すこと。`Page` や `Slice` は `Pageable` を持つこと。`Pageable` や `Sort` は最大一つ。`@Modifying` は `int`、`bool`、または何も返さないこと。`countQuery` は `Page` のためのものであること。`rowMapper` と `resultSetExtractor` は併用せず、`JdbcRow` や `JdbcResult` の関数であること。`@Lock` はないこと。行が結果になりうること。
- **テキスト:** 各 `:name` がメソッドのパラメーターであること。単なる `?` はないこと。`#{#entityName}` 以外の `#{...}` はないこと。
- **エンティティのプレースホルダー:** `{Book.authorId}` では、`Book` がアプリケーションの `@Table` クラスで、`authorId` が保存されるプロパティ (`@Transient` でも `@MappedCollection` でもない) であること。
- **綴りを間違えた名前:** `from`、`join`、`update`、`into`、`delete from` の後のテーブル、修飾された `alias.column`、修飾されていない列で、ビルドがその名前を知らないが近いものを知っている場合。

```text
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` を、実行される順に読みます。

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

- 何にも近くない名前 (別のスキーマのテーブル、関数、データベース固有の語) はそのままにされ、1 文字や 2 文字の名前も同様です。
- ビルドが部分的にしか理解できないテーブルやビューの列、`select *` の列、`${placeholder}` のテーブルの列はチェックされません。
- キーワード、関数、別名 (テーブル、列、CTE のもの)、キャスト、引用符で囲んだテキストは決して名前とみなされません。
- 独自の `NamingStrategy` の Bean は、エンティティから派生する名前を隠します。
- ビルドは `application.properties`、`application.yml`、`application.yaml` (`config/` 内のものも) から `spring.sql.migration.locations` と `spring.sql.init.schema-locations` を、`resources:` のロケーションだけ読みます。`file:` のロケーション、その中の `${placeholder}`、それらを設定するプロファイルのファイル、`spring.config.import`、`spring.config.location`、`spring.config.additional-location`、または名前付きのデータソースの設定があると、チェックは無効になります。
- ロケーションに `{vendor}` があると、各データベースのマイグレーションは選択肢になります。そのどれかにある列は既知とみなされます。

## 起動時

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

- `${property:default}` のプレースホルダーは Environment から解決されます。
- `{Entity}` の名前はマッピングを通して書かれます。
- ビルドがコンパイルしなかった SpEL の値は解析されます。
- `@Query` には SQL のストアが必要です。`@Query` メソッドを持つメモリ上のストアのリポジトリは起動を失敗させます。

## エディターで

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

## Spring (Java) との対応

```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 はリポジトリが作られるときにテキストをチェックしますが、ここではビルドがチェックします。

## 関連項目

- [派生クエリ](derived-queries.md)
- [JdbcTemplate と JdbcClient](jdbc.md)
- [スキーマとマイグレーション](schema.md)
