アノテーションインターフェース Query

リポジトリメソッドをクエリメソッドとしてアノテーション付けし、Jakarta Data Query Language (JDQL) または Jakarta Persistence Query Language (JPQL) で記述されたクエリを指定します。Jakarta Data プロバイダーは、リレーショナルデータストアを対象とする完全な JPQL 言語をサポートする必要はありません。ただし、特定のプロバイダーは、JDQL で必要なサブセットを超える JPQL の機能を提供したり、ターゲットデータストアテクノロジの特定の機能を対象とするベンダー固有の JDQL 拡張機能を提供したりする場合があります。このような拡張機能には、プロバイダー間またはデータベース間の移植性が保証されていません。

必須の value() メンバーは、JDQL または JPQL クエリを文字列として指定します。

select ステートメントの場合、クエリメソッドの戻り値の型は、クエリによって返される型と一致している必要があります。update または delete ステートメントの場合、戻り値は void、int、または long である必要があります。

SQL と比較すると、JDQL では select ステートメントの省略構文が許可されます。

• from 句は JDQL ではオプションです。この句がない場合、クエリ対象のエンティティはリポジトリメソッドの戻り値の型によって決定されます。戻り値の型がエンティティ型でない場合は、リポジトリのプライマリエンティティ型によって決定されます。
• select 句は、JDQL と JPQL の両方でオプションです。この句がない場合、クエリはクエリされたエンティティを返します。

クエリには次のような内容が含まれます。

• :name 形式の名前付きパラメーター（ラベル name は有効な Java 識別子）または
• ?n 形式の順序パラメーター。ラベル n は 1 から始まる連続した正の整数です。

特定のクエリでは、名前付きパラメーターと序数パラメーターを混在させることはできません。

アノテーション付きクエリメソッドの各パラメーターは、次のいずれかである必要があります。

• クエリの名前付きパラメーターとして、名前（Java ソース内のパラメーター名、または @Param によって割り当てられた名前）と型が正確に同じである
• メソッドのパラメーターリスト内の位置と型がクエリの位置パラメーターとまったく同じであるか
• 型は Limit、Order、PageRequest または Sort です。

Param アノテーションは、メソッドパラメーターを名前付きパラメーターに関連付けます。メソッドパラメーター名が名前付きパラメーターの名前と一致し、アプリケーションが -parameters コンパイラーオプションを使用してコンパイルされ、実行時にパラメーター名が使用可能になる場合、Param アノテーションは不要です。

メソッドパラメーターは、メソッドパラメーターリスト内の位置によって序数パラメーターに関連付けられます。メソッドの最初のパラメーターは、序数パラメーター ?1 に関連付けられます。

以下に例を示します。

 @Repository
 public interface People extends CrudRepository<Person, Long> {

     // JDQL with positional parameters
     @Query("where firstName = ?1 and lastName = ?2")
     List<Person> byName(String first, String last);

     // JDQL with a named parameter
     @Query("where firstName || ' ' || lastName like :pattern")
     List<Person> byName(String pattern);

     // JPQL using a positional parameter
     @Query("from Person where extract(year from birthdate) = ?1")
     List<Person> bornIn(int year);

     // JPQL using named parameters
     @Query("select distinct name from Person " +
            "where length(name) >= :min and length(name) <= :max")
     Page<String> namesOfLength(@Param("min") int minLength,
                                @Param("max") int maxLength,
                                PageRequest pageRequest,
                                Order<Person> order);

     ...
 }
 

@Query アノテーションが付けられたメソッドは、次のいずれかの型を返す必要があります。

• クエリ結果型 R（クエリが単一の結果を返す場合）
• Optional<R>、クエリが最大で 1 つの結果を返す場合
• 配列型 R[]
• List<R>,
• Stream<R>、または
• Page<R> または CursoredPage<R>。

このメソッドは、クエリ結果ごとにオブジェクトを返します。

• アノテーション付きメソッドの戻り値の型が R または Optional<R> であり、複数のレコードがクエリ制限を満たす場合、メソッドは NonUniqueResultException をスローする必要があります。
• アノテーション付きメソッドの戻り値の型が R であり、クエリ制限を満たすレコードがない場合、メソッドは EmptyResultException をスローする必要があります。

@Find、@Query、@Insert、@Update、@Delete、@Save などのアノテーションは相互に排他的です。リポジトリインターフェースの特定のメソッドには、最大で 1 つの @Find アノテーション、ライフサイクルアノテーション、クエリアノテーションを含めることができます。