better documentation for limit and friends

with code example

documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc

@@ -2007,19 +2007,14 @@ include::{sourcedir}/HQLTest.java[tags=hql-order-by-example]
 ----
 ====
 
+Queries with an ordered result list may have limits or pagination.
+
 [[hql-limit-offset]]
-=== Limits and offsets
+==== Limits and offsets
 
 It's often useful to place a hard upper limit on the number of results that may be returned by a query.
-
+The `limit` and `offset` clauses are an alternative to the use of `setMaxResults()` and `setFirstResult()` respectively,
-[NOTE]
+and also may be used for <<jpql-pagination>>.
-====
-_Limiting_ certainly _isn't_ a well-defined relational operation, and must be used with care.
-
-A limit can easily break the semantics of certain other features of HQL, including <<hql-explicit-fetch-join,fetch joins>>.
-====
-
-The `limit` and `offset` clauses are an alternative to the use of `setMaxResults()` and `setFirstResult()` respectively.
 
 [TIP]
 ====
@@ -2038,4 +2033,39 @@ include::{extrasdir}/limit_offset_bnf.txt[]
 ----
 ====
 
+These two queries are identical:
+
+[[hql-limit-example]]
+//.Order by example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-limit-example]
+----
+====
+
+These are well-defined limits: the number of results returned by `getMaxResults()` will be limited to 50, as promised.
+But not every query is quite so well-behaved.
+
+[NOTE]
+====
+_Limiting_ certainly _isn't_ a well-defined relational operation, and must be used with care.
+
+A limit can easily break the semantics of certain other features of HQL, including <<hql-explicit-fetch-join,fetch joins>>.
+====
+
+This next query is accepted by HQL, but the last `Phone` in the result list might have an incomplete collection of phones:
+
+[[hql-bad-limit-example]]
+//.Order by example
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-bad-limit-example]
+----
+====
+
+The `limit 50` here refers to the total number of rows returned from the database.
+The final number of ``Phone``s returned by `getResultList()` will be fewer, after Hibernate eliminates duplicate ``Phone``s from the result list.
+
 In the next chapter we'll see a completely different way to write queries in Hibernate.

documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java

@@ -2867,6 +2867,54 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 		});
 	}
 
+	@Test
+	public void test_hql_limit_example() {
+
+		doInJPA(this::entityManagerFactory, entityManager -> {
+			//tag::hql-limit-example[]
+			List<Call> calls1 = entityManager.createQuery(
+				"select c " +
+				"from Call c " +
+				"join c.phone p " +
+				"order by p.number " +
+				"limit 50",
+				Call.class)
+			.getResultList();
+
+			// same thing
+			List<Call> calls2 = entityManager.createQuery(
+				"select c " +
+				"from Call c " +
+				"join c.phone p " +
+				"order by p.number " +
+				"fetch first 50 rows only",
+				Call.class)
+			.getResultList();
+			//end::hql-limit-example[]
+		});
+	}
+
+	@Test
+	public void test_hql_bad_limit_example() {
+
+		doInJPA(this::entityManagerFactory, entityManager -> {
+			//tag::hql-bad-limit-example[]
+			// don't do this!
+			List<Phone> wrongCalls = entityManager.createQuery(
+				"select p " +
+				"from Phone p " +
+				// join fetch should not be used with limit
+				"join fetch p.calls " +
+				// but if you insist, at least sort by the collection owner
+				"order by p " +
+				// this won't be the final number of results!
+				"limit 50",
+				Phone.class)
+			.getResultList();
+			//end::hql-bad-limit-example[]
+		});
+	}
+
 	@Test
 	public void test_hql_read_only_entities_example() {