From 0640fe5e6bf84d01f33ad2306333439465ea788e Mon Sep 17 00:00:00 2001
From: Mark Paluch <mark.paluch@broadcom.com>
Date: Wed, 22 Jan 2025 14:11:25 +0100
Subject: [PATCH] =?UTF-8?q?Document=20that=20fluent=20`findBy(=E2=80=A6)`?=
 =?UTF-8?q?=20queries=20must=20return=20a=20result.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #3237
---
 .../data/querydsl/QuerydslPredicateExecutor.java              | 4 ++++
 .../data/querydsl/ReactiveQuerydslPredicateExecutor.java      | 4 ++++
 .../data/repository/query/QueryByExampleExecutor.java         | 4 ++++
 .../data/repository/query/ReactiveQueryByExampleExecutor.java | 4 ++++
 4 files changed, 16 insertions(+)

diff --git a/src/main/java/org/springframework/data/querydsl/QuerydslPredicateExecutor.java b/src/main/java/org/springframework/data/querydsl/QuerydslPredicateExecutor.java
index 5764d3505..996ed8263 100644
--- a/src/main/java/org/springframework/data/querydsl/QuerydslPredicateExecutor.java
+++ b/src/main/java/org/springframework/data/querydsl/QuerydslPredicateExecutor.java
@@ -115,6 +115,10 @@ public interface QuerydslPredicateExecutor<T> {
 	/**
 	 * Returns entities matching the given {@link Predicate} applying the {@link Function queryFunction} that defines the
 	 * query and its result type.
+	 * <p>
+	 * The query object used with {@code queryFunction} is only valid inside the `findBy(…)` method call. This requires
+	 * the query function to return a query result and not the {@link FluentQuery} object itself to ensure the query is
+	 * executed inside the {@code findBy(…)} method.
 	 *
 	 * @param predicate must not be {@literal null}.
 	 * @param queryFunction the query function defining projection, sorting, and the result type
diff --git a/src/main/java/org/springframework/data/querydsl/ReactiveQuerydslPredicateExecutor.java b/src/main/java/org/springframework/data/querydsl/ReactiveQuerydslPredicateExecutor.java
index 2d1758d29..f6ab711ab 100644
--- a/src/main/java/org/springframework/data/querydsl/ReactiveQuerydslPredicateExecutor.java
+++ b/src/main/java/org/springframework/data/querydsl/ReactiveQuerydslPredicateExecutor.java
@@ -136,6 +136,10 @@ public interface ReactiveQuerydslPredicateExecutor<T> {
 	/**
 	 * Returns entities matching the given {@link Predicate} applying the {@link Function queryFunction} that defines the
 	 * query and its result type.
+	 * <p>
+	 * The query object used with {@code queryFunction} is only valid inside the `findBy(…)` method call. This requires
+	 * the query function to return a query result and not the {@link FluentQuery} object itself to ensure the query is
+	 * executed inside the {@code findBy(…)} method.
 	 *
 	 * @param predicate must not be {@literal null}.
 	 * @param queryFunction the query function defining projection, sorting, and the result type
diff --git a/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java b/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java
index fb566fc4c..90e285359 100644
--- a/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java
+++ b/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java
@@ -95,6 +95,10 @@ public interface QueryByExampleExecutor<T> {
 	/**
 	 * Returns entities matching the given {@link Example} applying the {@link Function queryFunction} that defines the
 	 * query and its result type.
+	 * <p>
+	 * The query object used with {@code queryFunction} is only valid inside the `findBy(…)` method call. This requires
+	 * the query function to return a query result and not the {@link FluentQuery} object itself to ensure the query is
+	 * executed inside the {@code findBy(…)} method.
 	 *
 	 * @param example must not be {@literal null}.
 	 * @param queryFunction the query function defining projection, sorting, and the result type
diff --git a/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java b/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java
index e1cd5322d..631e64106 100644
--- a/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java
+++ b/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java
@@ -84,6 +84,10 @@ public interface ReactiveQueryByExampleExecutor<T> {
 	/**
 	 * Returns entities matching the given {@link Example} applying the {@link Function queryFunction} that defines the
 	 * query and its result type.
+	 * <p>
+	 * The query object used with {@code queryFunction} is only valid inside the `findBy(…)` method call. This requires
+	 * the query function to return a query result and not the {@link FluentQuery} object itself to ensure the query is
+	 * executed inside the {@code findBy(…)} method.
 	 *
 	 * @param example must not be {@literal null}.
 	 * @param queryFunction the query function defining projection, sorting, and the result type