mention ordered set functions in documentation

Author: gavinking

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

@@ -1915,6 +1915,36 @@ include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-filter-example]
 ----
 ====
 
+[[hql-aggregate-functions-orderedset]]
+==== Ordered set aggregate functions
+
+_Ordered set aggregate functions_ are special aggregate functions that have:
+
+- not only an optional filter clause, but also
+- a _within group clause_, a mini-`order by` clause.
+
+IMPORTANT: Ordered set aggregate functions are not available on every database.
+
+The most widely-supported ordered set aggregate function is one which builds a string by concatenating the values within a group.
+This function has different names on different databases, but HQL abstracts these differences, and—following ANSI SQL—calls it `listagg()`.
+
+[[hql-aggregate-functions-within-group-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-aggregate-functions-within-group-example]
+----
+====
+
+The following ordered set aggregate functions are also available on many platforms:
+
+|===
+| Type | functions
+
+| Inverse distribution functions | `mode()`, `percentile_cont()`, `percentile_disc()`
+| Hypothetical set functions | `rank()`, `dense_rank()`, `percent_rank()`, `cume_dist()`
+|===
+
 [[hql-where-clause]]
 === Restriction: `where`
 

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

@@ -1454,6 +1454,22 @@ public void test_hql_aggregate_functions_filter_example() {
 		});
 	}
 
+	@Test @SkipForDialect(DerbyDialect.class)
+	public void test_hql_aggregate_functions_within_group_example() {
+		doInJPA(this::entityManagerFactory, entityManager -> {
+			//tag::hql-aggregate-functions-within-group-example[]
+
+			List<String> callCount = entityManager.createQuery(
+				"select listagg(p.number, ', ') within group (order by p.type,p.number) " +
+				"from Phone p " +
+				"group by p.person",
+				String.class)
+			.getResultList();
+			//end::hql-aggregate-functions-within-group-example[]
+			assertNotNull(callCount.get(0));
+		});
+	}
+
 	@Test
 	@SkipForDialect(value = DerbyDialect.class, comment = "See https://issues.apache.org/jira/browse/DERBY-2072")
 	public void test_hql_concat_function_example() {