}, where {@code C} is {@link Constraint} or any
+ * interface which extends {@link Constraint} and {@code T} is the type of
+ * the persistent attribute,
+ * have exactly the same name as a persistent attribute of the entity class,
+ * be annotated {@link Is @Is(C.class)}, where {@code C} is an interface
+ * which extends {@link Constraint}, and be of the same type as the parameter
+ * of a unary static method of {@code C} returning {@code C} where {@code T}
+ * is the type of the persistent attribute, or
+ * be of type {@link Restriction}, {@link Sort}, {@link Order}, {@link Limit},
+ * or {@link PageRequest}.
*
* The query is inferred from the method parameters which match attributes of
* the entity.
diff --git a/api/src/main/java/jakarta/data/repository/Query.java b/api/src/main/java/jakarta/data/repository/Query.java
index d46f0bdcb..8671dc92e 100644
--- a/api/src/main/java/jakarta/data/repository/Query.java
+++ b/api/src/main/java/jakarta/data/repository/Query.java
@@ -99,8 +99,8 @@
* of the query,
* have exactly the same type and position within the parameter list of
* the method as a positional parameter of the query, or
- * be of type {@link Limit}, {@link Order}, {@link PageRequest},
- * {@link Restriction}, or {@link Sort}.
+ * be of type {@link Restriction}, {@link Sort}, {@link Order}, {@link Limit},
+ * or {@link PageRequest}.
*
*
* The {@link Param} annotation associates a method parameter with a named
diff --git a/spec/src/main/asciidoc/repository.asciidoc b/spec/src/main/asciidoc/repository.asciidoc
index 515905cd1..d83a13b8f 100644
--- a/spec/src/main/asciidoc/repository.asciidoc
+++ b/spec/src/main/asciidoc/repository.asciidoc
@@ -120,7 +120,7 @@ Each parameter of an annotated query method must either:
- have exactly the same name and type as a named parameter of the query,
- have exactly the same type and position within the parameter list of the method as a positional parameter of the query, or
-- be of type `Limit`, `Order`, `PageRequest`, or `Sort`.
+- be of type `Restriction`, `Sort`, `Order`, `Limit`, or `PageRequest`.
A repository with annotated query methods with named parameters must be compiled so that parameter names are preserved in the class file (for example, using `javac -parameters`), or the parameter names must be specified explicitly using the `@Param` annotation.
@@ -186,8 +186,10 @@ Each automatic query method must be assigned an entity type. The rules for infer
Jakarta Data infers a query based on the parameters of the method. Each parameter must either:
-- have exactly the same type and name as a persistent attribute of the entity class, or
-- be of type `Limit`, `Order`, `PageRequest`, or `Sort`.
+- have exactly the same type and name as a persistent attribute of the entity class,
+- have exactly the same name as a persistent attribute of the entity class and be of type `C`, where `C` is `Constraint` or any interface which extends `Constraint` and `T` is the type of the persistent attribute,
+- have exactly the same name as a persistent attribute of the entity class, be annotated `@Is(C.class)`, where `C` is an interface which extends `Constraint`, and be of the same type as the parameter of a unary static method of `C` returning `C` where `T` is the type of the persistent attribute, or
+- be of type `Restriction`, `Sort`, `Order`, `Limit`, or `PageRequest`.
Parameter names map parameters to persistent attributes. A repository with parameter-based automatic query methods must either:
@@ -265,20 +267,34 @@ If a method of a repository interface has more than one such annotation, the ann
reject such a method declaration at compile time.
-=== Special parameters for limits, sorting, and pagination
+=== Special parameters for additional filtering, limits, sorting, and pagination
-An <>, <>, or Query by Method Name query method may have _special parameters_ of type `Limit`, `Order`, `Sort`, or `PageRequest` if the method return type indicates that the method may return multiple entities, that is, if the return type is:
+An <>, <>, or Query by Method Name query method may have _special parameters_ of type `Sort`, `Order`, `Limit`, or `PageRequest` if the method return type indicates that the method may return multiple entities, that is, if the return type is:
- an array type,
- `List` or `Stream`, or
- `Page` or `CursoredPage`.
+Any <> or <> query method may also have a special parameter of type `Restriction`.
+
A special parameter controls which query results are returned to the caller of a repository method, or in what order the results are returned:
-- a `Limit` allows the query results to be limited to a given range defined in terms of an offset and maximum number of results,
-- a `Sort` or `Order` allows the query results to be sorted by a given entity attribute or list of attributes, respectively, and
+- a `Restriction` allows the query results to be restricted by applying constraints to entity attributes,
+- a `Sort` or `Order` allows the query results to be sorted by a given entity attribute or list of attributes, respectively,
+- a `Limit` allows the query results to be limited to a given range defined in terms of an offset and maximum number of results, and
- a `PageRequest` splits results into pages. A parameter of this type must be declared when the repository method returns a `Page` of results, as specified below in <>, or a `CursoredPage`, as specified in <>.
+The types `Restriction`, `Sort`, and `Order` are parameterized by an entity type.
+Any special parameter declared with one of these types must be declared with type argument `E` or `? super E` where `E` is the queried entity type.
+
+For example, this repository method allows a list of cars to be filtered and sorted by attributes of `Car` or of its supertype `Vehicle`:
+
+[source,java]
+----
+List cars(Restriction restriction,
+ Order order);
+----
+
A repository method must throw `UnsupportedOperationException` if it has:
- more than one parameter of type `PageRequest` or `Limit`,