HHH-17410 Add documentation for count query creation

documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc

@@ -32,6 +32,7 @@ include::chapters/events/Events.adoc[]
 include::chapters/query/hql/Query.adoc[]
 include::chapters/query/hql/QueryLanguage.adoc[]
 include::chapters/query/criteria/Criteria.adoc[]
+include::chapters/query/criteria/CriteriaExtensions.adoc[]
 include::chapters/query/native/Native.adoc[]
 include::chapters/query/spatial/Spatial.adoc[]
 include::chapters/query/extensions/Vector.adoc[]

documentation/src/main/asciidoc/userguide/chapters/query/criteria/CriteriaExtensions.adoc

@@ -0,0 +1,34 @@
+[[criteria-extensions]]
+== Criteria extensions
+:root-project-dir: ../../../../../../../..
+:core-project-dir: {root-project-dir}/hibernate-core
+:example-dir-criteria: {core-project-dir}/src/test/java/org/hibernate/orm/test/query/criteria
+
+Hibernate ORM provides extensions to the JPA Criteria API to allow making use of HQL features through the Criteria API.
+
+The `Session` interface gives access to the `org.hibernate.query.criteria.HibernateCriteriaBuilder`,
+a subtype of `jakarta.persistence.criteria.CriteriaBuilder`,
+through the `Session#getCriteriaBuilder()` method, which is the entry point to the extensions.
+
+The `HibernateCriteriaBuilder` interface offers additional methods, but also provides co-variant overridden methods,
+which return subtypes of that the respective `jakarta.persistence.criteria.CriteriaBuilder` methods return types.
+The subtypes are consistently named by prefixing `Jpa` i.e. `Expression` becomes `JpaExpression`.
+
+These subtypes provide additional methods and co-variant overrides to ease working with the extensions.
+
+[[criteria-extensions-count-query]]
+=== Count query creation
+
+A very common requirement is the creation of a count query based on an existing query.
+This can be done by using the `JpaCriteriaQuery#createCountQuery()` method.
+
+[[criteria-extensions-count-query-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{example-dir-criteria}/CountQueryTests.java[tags=criteria-extensions-count-query-example]
+----
+====
+
+The resulting count query will wrap a copy of the original query as subquery in the from clause and select `count(*)`.
+

hibernate-core/src/test/java/org/hibernate/orm/test/query/criteria/CountQueryTests.java

@@ -4,7 +4,7 @@
  * License: GNU Lesser General Public License (LGPL), version 2.1 or later
  * See the lgpl.txt file in the root directory or http://www.gnu.org/licenses/lgpl-2.1.html
  */
-package org.hibernate.orm.test.query;
+package org.hibernate.orm.test.query.criteria;
 
 import java.time.LocalDate;
 import java.util.List;
@@ -129,21 +129,22 @@ public class CountQueryTests {
 	public void testParameters(SessionFactoryScope scope) {
 		scope.inTransaction(
 				session -> {
+					//tag::criteria-extensions-count-query-example[]
 					final HibernateCriteriaBuilder cb = session.getCriteriaBuilder();
 					final JpaCriteriaQuery<Tuple> cq = cb.createTupleQuery();
 					final JpaRoot<Contact> root = cq.from( Contact.class );
-					cq.multiselect(
-							root.get( "id" ),
-							root.get( "name" )
-					);
 					final JpaParameterExpression<Contact.Gender> parameter = cb.parameter( Contact.Gender.class );
+					
+					cq.multiselect( root.get( "id" ), root.get( "name" ) );
 					cq.where( root.get( "gender" ).equalTo( parameter ) );
-					final List<Tuple> resultList = session.createQuery( cq )
-							.setParameter( parameter, Contact.Gender.FEMALE )
-							.getResultList();
 					final Long count = session.createQuery( cq.createCountQuery() )
 							.setParameter( parameter, Contact.Gender.FEMALE )
 							.getSingleResult();
+					//end::criteria-extensions-count-query-example[]
+
+					final List<Tuple> resultList = session.createQuery( cq )
+							.setParameter( parameter, Contact.Gender.FEMALE )
+							.getResultList();
 					assertEquals( resultList.size(), count.intValue() );
 				}
 		);