From 2f60e08c6436e71e0cc06a2d98fe1008f40ef981 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 22 Jan 2024 15:13:55 +0100
Subject: [PATCH] add a NOTE to make something clearer

---
 .../src/main/asciidoc/querylanguage/Expressions.adoc        | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/documentation/src/main/asciidoc/querylanguage/Expressions.adoc b/documentation/src/main/asciidoc/querylanguage/Expressions.adoc
index fbe66e77eb..df0aaf6ee3 100644
--- a/documentation/src/main/asciidoc/querylanguage/Expressions.adoc
+++ b/documentation/src/main/asciidoc/querylanguage/Expressions.adoc
@@ -917,8 +917,6 @@ In case 2, application of the function produces an <<implicit-collection-join,im
 The next group of functions always accept a compound path referring to a collection or many-valued association of an entity.
 They're interpreted as referring to the collection as a whole.
 
-Application of one of these function produces implicit subquery.
-
 [[collective-collection-functions]]
 [cols="15,20,~,^15"]
 |===
@@ -929,6 +927,7 @@ Application of one of these function produces implicit subquery.
 | `keys()` | Maps | The keys of a map, collectively | ✖
 | `values()` | Maps | The values of a map, collectively | ✖
 |===
+Application of one of these function produces an implicit subquery or implicit join.
 
 This query has an implicit join:
 
@@ -946,6 +945,9 @@ This query has an implicit subquery:
 select title from Book where 'hibernate' in elements(tags)
 ----
 
+NOTE: It never makes sense to apply the functions `elements()`, `indices()`, `keys()`, or `values()` to an identification variable or single-valued path expression.
+These functions must be applied to a reference to a many-valued path expression.
+
 [discrete]
 ===== Collection sizes