HHH-16861 documentation for HQL ordinal() function

Added `ordinal` to QueryLanguage.adoc
Added `ordinal` to Expressions.adoc

Update documentation/src/main/asciidoc/querylanguage/Expressions.adoc

Co-authored-by: Gavin King <[email protected]>

Author: 2 people

documentation/src/main/asciidoc/querylanguage/Expressions.adoc

@@ -547,6 +547,7 @@ The following special functions make it possible to discover or narrow expressio
 | `treat()` | Narrow an entity or embeddable type | `treat(e as Entity)` | ✔
 | `cast()` | Narrow a basic type | `cast(x as Type)` | ✖
 | `str()` | Cast to a string | `str(x)` | ✖
+| `ordinal()` | Get the ordinal value of an enum | `ordinal(x)` | ✖
 |===
 
 Let's see what these functions do.
@@ -616,6 +617,18 @@ The function `str(x)` is a synonym for `cast(x as String)`.
 select str(id) from Order
 ----
 
+[[function-ordinal]]
+[discrete]
+===== Extracting the ordinal value of an enum
+
+The function `ordinal(x)` extracts the ordinal value of an enum.
+It supports both enum fields mapped as `ORDINAL` and `STRING`.
+
+[source, hql]
+----
+select ordinal(p.type) from Phone p
+----
+
 [[functions-null]]
 ==== Functions for working with null values
 

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

@@ -820,7 +820,23 @@ The function `str(x)` is a synonym for `cast(x as String)`.
 ----
 include::{example-dir-hql}/HQLTest.java[tags=hql-str-function-example]
 ----
+
+====
+
+[[hql-function-ordinal]]
+===== `ordinal()`
+
+The function `ordinal(x)` extracts the ordinal value of an enum.
+It supports both enum fields mapped as `ORDINAL` and `STRING`.
+
 ====
+[source, java, indent=0]
+----
+include::{example-dir-hql}/EnumTest.java[tags=hql-ordinal-function-example]
+----
+
+====
+
 
 [[hql-functions-null]]
 ==== Functions for working with null values

hibernate-core/src/test/java/org/hibernate/orm/test/hql/EnumTest.java

@@ -76,15 +76,21 @@ public void testOrdinalFunctionOnOrdinalEnum(SessionFactoryScope scope) {
 	@Test
 	public void testOrdinalFunctionOnStringEnum(SessionFactoryScope scope) {
 		scope.inTransaction( session -> {
+			//tag::hql-ordinal-function-example[]
+			// enum Gender {
+			//	MALE,
+			//	FEMALE,
+			//	OTHER
+			//}
 			List<Integer> femaleOrdinalFromString = session.createQuery(
-							"select ordinal(gender)" +
-									"from EntityOfBasics e " +
-									"where e.gender = :gender",
-							Integer.class
-					)
+					"select ordinal(gender)" +
+					"from EntityOfBasics e " +
+					"where e.gender = :gender",
+					Integer.class )
 					.setParameter( "gender", EntityOfBasics.Gender.FEMALE )
 					.getResultList();
-
+			//	This will return List.of(1)
+			//end::hql-ordinal-function-example[]
 			assertThat( femaleOrdinalFromString ).hasSize( 1 );
 			assertThat( femaleOrdinalFromString ).hasSameElementsAs( List.of( 1 ) );
 		} );