HHH-18496 Add json_arrayagg

Author: beikov

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

@@ -1634,6 +1634,7 @@ The following functions deal with SQL JSON types, which are not supported on eve
 | `json_value()` | Extracts a value from a JSON document by JSON path
 | `json_exists()` | Checks if a JSON path exists in a JSON document
 | `json_query()` | Queries non-scalar values by JSON path in a JSON document
+| `json_arrayagg()` | Creates a JSON array by aggregating values
 |===
 
 
@@ -1919,6 +1920,49 @@ Depending on the database, an error might still be thrown even without that, but
 
 NOTE: The H2 emulation only supports absolute JSON paths using the dot notation.
 
+[[hql-json-arrayagg-function]]
+===== `json_arrayagg()`
+
+Creates a JSON array by aggregating values.
+
+[[hql-json-arrayagg-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/json_arrayagg_bnf.txt[]
+----
+
+This aggregate function is similar to an <<hql-aggregate-functions-orderedset,_ordered set aggregate function_>>
+since it allows to specify the order in which elements are aggregated, but uses a special syntax.
+
+[[hql-json-arrayagg-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonArrayAggregateTest.java[tags=hql-json-arrayagg-example]
+----
+====
+
+Although database dependent, usually `null` values are `absent` in the resulting JSON array.
+To retain `null` elements, use the `null on null` clause.
+
+[[hql-json-arrayagg-null-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonArrayAggregateTest.java[tags=hql-json-arrayagg-null-example]
+----
+====
+
+The order in which elements are aggregated can be defined by specifying an order by clause.
+
+[[hql-json-arrayagg-order-by-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonArrayAggregateTest.java[tags=hql-json-arrayagg-order-by-example]
+----
+====
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 

documentation/src/main/asciidoc/userguide/chapters/query/hql/extras/json_arrayagg_bnf.txt

@@ -0,0 +1,5 @@
+"json_arrayagg(" expressionOrPredicate jsonNullClause? orderByClause? ")" filterClause?
+
+jsonNullClause
+	: ("absent"|"null") "on null"
+	;

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/DB2LegacyDialect.java

@@ -436,6 +436,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.jsonExists_no_passing();
 				functionFactory.jsonObject_db2();
 				functionFactory.jsonArray_db2();
+				functionFactory.jsonArrayAgg_db2();
 			}
 		}
 	}

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java

@@ -406,6 +406,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 					functionFactory.jsonValue_h2();
 					functionFactory.jsonQuery_h2();
 					functionFactory.jsonExists_h2();
+					functionFactory.jsonArrayAgg_h2();
 				}
 			}
 			else {

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/HSQLLegacyDialect.java

@@ -273,6 +273,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		if ( getVersion().isSameOrAfter( 2, 7 ) ) {
 			functionFactory.jsonObject_hsqldb();
 			functionFactory.jsonArray_hsqldb();
+			functionFactory.jsonArrayAgg_hsqldb();
 		}
 
 		//trim() requires parameters to be cast when used as trim character

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/MariaDBLegacyDialect.java

@@ -92,6 +92,8 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			);
 			commonFunctionFactory.jsonValue_mariadb();
 			commonFunctionFactory.jsonArray_mariadb();
+			commonFunctionFactory.jsonQuery_mariadb();
+			commonFunctionFactory.jsonArrayAgg_mariadb();
 			if ( getVersion().isSameOrAfter( 10, 3, 3 ) ) {
 				commonFunctionFactory.inverseDistributionOrderedSetAggregates_windowEmulation();
 				functionContributions.getFunctionRegistry().patternDescriptorBuilder( "median", "median(?1) over ()" )

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/MySQLLegacyDialect.java

@@ -658,6 +658,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonExists_mysql();
 			functionFactory.jsonObject_mysql();
 			functionFactory.jsonArray_mysql();
+			functionFactory.jsonArrayAgg_mysql();
 		}
 	}
 

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java

@@ -327,6 +327,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonExists_oracle();
 			functionFactory.jsonObject_oracle();
 			functionFactory.jsonArray_oracle();
+			functionFactory.jsonArrayAgg_oracle();
 		}
 	}
 

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java

@@ -638,6 +638,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonExists();
 			functionFactory.jsonObject();
 			functionFactory.jsonArray();
+			functionFactory.jsonArrayAgg();
 		}
 		else {
 			functionFactory.jsonValue_postgresql();
@@ -646,10 +647,12 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			if ( getVersion().isSameOrAfter( 16 ) ) {
 				functionFactory.jsonObject();
 				functionFactory.jsonArray();
+				functionFactory.jsonArrayAgg();
 			}
 			else {
 				functionFactory.jsonObject_postgresql();
 				functionFactory.jsonArray_postgresql();
+				functionFactory.jsonArrayAgg_postgresql();
 			}
 		}
 

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/SQLServerLegacyDialect.java

@@ -409,6 +409,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
+			functionFactory.jsonArrayAgg_sqlserver();
 		}
 		if ( getVersion().isSameOrAfter( 16 ) ) {
 			functionFactory.leastGreatest();