HHH-17355 Add array_to_string function

beikov · beikov · commit 79e3af546429 · 2023-11-06T18:01:04.000+01:00
diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
@@ -1138,6 +1138,7 @@ The following functions deal with SQL array types, which are not supported on ev
 | `array_replace()` | Creates array copy replacing a given element with another
 | `array_trim()` | Creates array copy trimming the last _N_ elements
 | `array_fill()` | Creates array filled with the same element _N_ times
+| `array_to_string()` | String representation of non-null array elements
 |===
 
 ===== `array()`
@@ -1429,6 +1430,19 @@ include::{array-example-dir-hql}/ArrayFillTest.java[tags=hql-array-fill-example]
 ----
 ====
 
+===== `array_to_string()`
+
+Concatenates the non-null array elements with a separator, as specified by the arguments.
+Returns `null` if the first argument is `null`.
+
+[[hql-array-to-string-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{array-example-dir-hql}/ArrayToStringTest.java[tags=hql-array-to-string-example]
+----
+====
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CockroachLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CockroachLegacyDialect.java
@@ -479,6 +479,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_postgresql();
+		functionFactory.arrayToString_postgresql();
 
 		functionContributions.getFunctionRegistry().register(
 				"trunc",
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java
@@ -388,6 +388,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.arrayReplace_h2( getMaximumArraySize() );
 				functionFactory.arrayTrim_trim_array();
 				functionFactory.arrayFill_h2();
+				functionFactory.arrayToString_h2( getMaximumArraySize() );
 			}
 			else {
 				// Use group_concat until 2.x as listagg was buggy
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/HSQLLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/HSQLLegacyDialect.java
@@ -265,6 +265,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace_unnest();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_hsql();
+		functionFactory.arrayToString_hsql();
 	}
 
 	@Override
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java
@@ -301,6 +301,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace_oracle();
 		functionFactory.arrayTrim_oracle();
 		functionFactory.arrayFill_oracle();
+		functionFactory.arrayToString_oracle();
 	}
 
 	@Override
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java
@@ -599,6 +599,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_postgresql();
+		functionFactory.arrayToString_postgresql();
 
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java
@@ -466,6 +466,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_postgresql();
+		functionFactory.arrayToString_postgresql();
 
 		functionContributions.getFunctionRegistry().register(
 				"trunc",
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/H2Dialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/H2Dialect.java
@@ -327,6 +327,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace_h2( getMaximumArraySize() );
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_h2();
+		functionFactory.arrayToString_h2( getMaximumArraySize() );
 	}
 
 	/**
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/HSQLDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/HSQLDialect.java
@@ -205,6 +205,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace_unnest();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_hsql();
+		functionFactory.arrayToString_hsql();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/OracleArrayJdbcType.java b/hibernate-core/src/main/java/org/hibernate/dialect/OracleArrayJdbcType.java
@@ -541,6 +541,29 @@ public void addAuxiliaryDatabaseObjects(
 						false
 				)
 		);
+		database.addAuxiliaryDatabaseObject(
+				new NamedAuxiliaryDatabaseObject(
+						arrayTypeName + "_to_string",
+						database.getDefaultNamespace(),
+						new String[]{
+								"create or replace function " + arrayTypeName + "_to_string(arr in " + arrayTypeName +
+										", sep in varchar2) return varchar2 deterministic is " +
+										"res varchar2(4000):=''; begin " +
+										"if arr is null or sep is null then return null; end if; " +
+										"for i in 1 .. arr.count loop " +
+										"if arr(i) is not null then " +
+										"if length(res)<>0 then res:=res||sep; end if; " +
+										"res:=res||arr(i); " +
+										"end if; " +
+										"end loop; " +
+										"return res; " +
+										"end;"
+						},
+						new String[] { "drop function " + arrayTypeName + "_to_string" },
+						emptySet(),
+						false
+				)
+		);
 	}
 
 	protected String createOrReplaceConcatFunction(String arrayTypeName) {
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java
@@ -330,6 +330,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace_oracle();
 		functionFactory.arrayTrim_oracle();
 		functionFactory.arrayFill_oracle();
+		functionFactory.arrayToString_oracle();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java
@@ -647,6 +647,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayReplace();
 		functionFactory.arrayTrim_trim_array();
 		functionFactory.arrayFill_postgresql();
+		functionFactory.arrayToString_postgresql();
 
 		functionFactory.makeDateTimeTimestamp();
 		// Note that PostgreSQL doesn't support the OVER clause for ordered set-aggregate functions
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java
@@ -31,6 +31,7 @@
 import org.hibernate.dialect.function.array.ArrayReplaceUnnestFunction;
 import org.hibernate.dialect.function.array.ArraySetUnnestFunction;
 import org.hibernate.dialect.function.array.ArraySliceUnnestFunction;
+import org.hibernate.dialect.function.array.ArrayToStringFunction;
 import org.hibernate.dialect.function.array.ArrayViaArgumentReturnTypeResolver;
 import org.hibernate.dialect.function.array.ElementViaArrayArgumentReturnTypeResolver;
 import org.hibernate.dialect.function.array.H2ArrayContainsFunction;
@@ -42,12 +43,14 @@
 import org.hibernate.dialect.function.array.H2ArrayRemoveIndexFunction;
 import org.hibernate.dialect.function.array.H2ArrayReplaceFunction;
 import org.hibernate.dialect.function.array.H2ArraySetFunction;
+import org.hibernate.dialect.function.array.H2ArrayToStringFunction;
 import org.hibernate.dialect.function.array.HSQLArrayConstructorFunction;
 import org.hibernate.dialect.function.array.HSQLArrayFillFunction;
 import org.hibernate.dialect.function.array.HSQLArrayPositionFunction;
 import org.hibernate.dialect.function.array.HSQLArrayPositionsFunction;
 import org.hibernate.dialect.function.array.HSQLArrayRemoveFunction;
 import org.hibernate.dialect.function.array.HSQLArraySetFunction;
+import org.hibernate.dialect.function.array.HSQLArrayToStringFunction;
 import org.hibernate.dialect.function.array.OracleArrayConcatElementFunction;
 import org.hibernate.dialect.function.array.OracleArrayConcatFunction;
 import org.hibernate.dialect.function.array.OracleArrayFillFunction;
@@ -61,6 +64,7 @@
 import org.hibernate.dialect.function.array.OracleArrayReplaceFunction;
 import org.hibernate.dialect.function.array.OracleArraySetFunction;
 import org.hibernate.dialect.function.array.OracleArraySliceFunction;
+import org.hibernate.dialect.function.array.OracleArrayToStringFunction;
 import org.hibernate.dialect.function.array.OracleArrayTrimFunction;
 import org.hibernate.dialect.function.array.PostgreSQLArrayConcatElementFunction;
 import org.hibernate.dialect.function.array.PostgreSQLArrayConcatFunction;
@@ -3194,4 +3198,32 @@ public void arrayFill_postgresql() {
 	public void arrayFill_oracle() {
 		functionRegistry.register( "array_fill", new OracleArrayFillFunction() );
 	}
+
+	/**
+	 * H2 array_to_string() function
+	 */
+	public void arrayToString_h2(int maximumArraySize) {
+		functionRegistry.register( "array_to_string", new H2ArrayToStringFunction( maximumArraySize, typeConfiguration ) );
+	}
+
+	/**
+	 * HSQL array_to_string() function
+	 */
+	public void arrayToString_hsql() {
+		functionRegistry.register( "array_to_string", new HSQLArrayToStringFunction( typeConfiguration ) );
+	}
+
+	/**
+	 * CockroachDB and PostgreSQL array_to_string() function
+	 */
+	public void arrayToString_postgresql() {
+		functionRegistry.register( "array_to_string", new ArrayToStringFunction( typeConfiguration ) );
+	}
+
+	/**
+	 * Oracle array_to_string() function
+	 */
+	public void arrayToString_oracle() {
+		functionRegistry.register( "array_to_string", new OracleArrayToStringFunction( typeConfiguration ) );
+	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayToStringFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayToStringFunction.java
@@ -0,0 +1,60 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * 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.dialect.function.array;
+
+import java.util.List;
+
+import org.hibernate.query.ReturnableType;
+import org.hibernate.query.sqm.function.AbstractSqmSelfRenderingFunctionDescriptor;
+import org.hibernate.query.sqm.function.FunctionKind;
+import org.hibernate.query.sqm.produce.function.ArgumentTypesValidator;
+import org.hibernate.query.sqm.produce.function.StandardArgumentsValidators;
+import org.hibernate.query.sqm.produce.function.StandardFunctionArgumentTypeResolvers;
+import org.hibernate.query.sqm.produce.function.StandardFunctionReturnTypeResolvers;
+import org.hibernate.sql.ast.SqlAstTranslator;
+import org.hibernate.sql.ast.spi.SqlAppender;
+import org.hibernate.sql.ast.tree.SqlAstNode;
+import org.hibernate.type.StandardBasicTypes;
+import org.hibernate.type.spi.TypeConfiguration;
+
+import static org.hibernate.query.sqm.produce.function.FunctionParameterType.ANY;
+import static org.hibernate.query.sqm.produce.function.FunctionParameterType.STRING;
+
+/**
+ * @author Christian Beikov
+ */
+public class ArrayToStringFunction extends AbstractSqmSelfRenderingFunctionDescriptor {
+
+	public ArrayToStringFunction(TypeConfiguration typeConfiguration) {
+		super(
+				"array_to_string",
+				FunctionKind.NORMAL,
+				StandardArgumentsValidators.composite(
+					new ArgumentTypesValidator( null, ANY, STRING ),
+					ArrayArgumentValidator.DEFAULT_INSTANCE
+				),
+				StandardFunctionReturnTypeResolvers.invariant(
+						typeConfiguration.getBasicTypeRegistry().resolve( StandardBasicTypes.STRING )
+				),
+				StandardFunctionArgumentTypeResolvers.invariant( typeConfiguration, ANY, STRING )
+		);
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> sqlAstArguments,
+			ReturnableType<?> returnType,
+			SqlAstTranslator<?> walker) {
+		sqlAppender.appendSql( "array_to_string(" );
+		sqlAstArguments.get( 0 ).accept( walker );
+		sqlAppender.appendSql( ',' );
+		sqlAstArguments.get( 1 ).accept( walker );
+		sqlAppender.appendSql( ')' );
+	}
+
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/H2ArrayToStringFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/H2ArrayToStringFunction.java
@@ -0,0 +1,52 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * 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.dialect.function.array;
+
+import java.util.List;
+
+import org.hibernate.query.ReturnableType;
+import org.hibernate.sql.ast.SqlAstTranslator;
+import org.hibernate.sql.ast.spi.SqlAppender;
+import org.hibernate.sql.ast.tree.SqlAstNode;
+import org.hibernate.sql.ast.tree.expression.Expression;
+import org.hibernate.type.spi.TypeConfiguration;
+
+/**
+ * H2 requires a very special emulation, because {@code unnest} is pretty much useless,
+ * due to https://github.com/h2database/h2database/issues/1815.
+ * This emulation uses {@code array_get}, {@code array_length} and {@code system_range} functions to roughly achieve the same.
+ */
+public class H2ArrayToStringFunction extends ArrayToStringFunction {
+
+	private final int maximumArraySize;
+
+	public H2ArrayToStringFunction(int maximumArraySize, TypeConfiguration typeConfiguration) {
+		super( typeConfiguration );
+		this.maximumArraySize = maximumArraySize;
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> sqlAstArguments,
+			ReturnableType<?> returnType,
+			SqlAstTranslator<?> walker) {
+		final Expression arrayExpression = (Expression) sqlAstArguments.get( 0 );
+		final Expression separatorExpression = (Expression) sqlAstArguments.get( 1 );
+		sqlAppender.append( "case when " );
+		arrayExpression.accept( walker );
+		sqlAppender.append( " is not null then coalesce((select listagg(array_get(" );
+		arrayExpression.accept( walker );
+		sqlAppender.append(",i.idx)," );
+		separatorExpression.accept( walker );
+		sqlAppender.append( ") within group (order by i.idx) from system_range(1,");
+		sqlAppender.append( Integer.toString( maximumArraySize ) );
+		sqlAppender.append( ") i(idx) where i.idx<=coalesce(cardinality(");
+		arrayExpression.accept( walker );
+		sqlAppender.append("),0)),'') end" );
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/HSQLArrayToStringFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/HSQLArrayToStringFunction.java
@@ -0,0 +1,45 @@
+/*
+ * Hibernate, Relational Persistence for Idiomatic Java
+ *
+ * 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.dialect.function.array;
+
+import java.util.List;
+
+import org.hibernate.query.ReturnableType;
+import org.hibernate.sql.ast.SqlAstNodeRenderingMode;
+import org.hibernate.sql.ast.SqlAstTranslator;
+import org.hibernate.sql.ast.spi.SqlAppender;
+import org.hibernate.sql.ast.tree.SqlAstNode;
+import org.hibernate.sql.ast.tree.expression.Expression;
+import org.hibernate.type.spi.TypeConfiguration;
+
+/**
+ * HSQLDB has a special syntax.
+ */
+public class HSQLArrayToStringFunction extends ArrayToStringFunction {
+
+	public HSQLArrayToStringFunction(TypeConfiguration typeConfiguration) {
+		super( typeConfiguration );
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> sqlAstArguments,
+			ReturnableType<?> returnType,
+			SqlAstTranslator<?> walker) {
+		final Expression arrayExpression = (Expression) sqlAstArguments.get( 0 );
+		final Expression separatorExpression = (Expression) sqlAstArguments.get( 1 );
+		sqlAppender.append( "case when " );
+		arrayExpression.accept( walker );
+		sqlAppender.append( " is not null then coalesce((select group_concat(t.val order by t.idx separator " );
+		// HSQLDB doesn't like non-literals as separator
+		walker.render( separatorExpression, SqlAstNodeRenderingMode.INLINE_PARAMETERS );
+		sqlAppender.append( ") from unnest(");
+		arrayExpression.accept( walker );
+		sqlAppender.append(") with ordinality t(val,idx)),'') end" );
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/OracleArrayToStringFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/OracleArrayToStringFunction.java
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayAggregateTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayAggregateTest.java
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayToStringTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayToStringTest.java

Original file line number	Diff line number	Diff line change
`@@ -388,6 +388,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`388`	`388`	`functionFactory.arrayReplace_h2( getMaximumArraySize() );`
`389`	`389`	`functionFactory.arrayTrim_trim_array();`
`390`	`390`	`functionFactory.arrayFill_h2();`
	`391`	`+ functionFactory.arrayToString_h2( getMaximumArraySize() );`
`391`	`392`	`}`
`392`	`393`	`else {`
`393`	`394`	`// Use group_concat until 2.x as listagg was buggy`
Original file line number	Diff line number	Diff line change
`@@ -265,6 +265,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`265`	`265`	`functionFactory.arrayReplace_unnest();`
`266`	`266`	`functionFactory.arrayTrim_trim_array();`
`267`	`267`	`functionFactory.arrayFill_hsql();`
	`268`	`+ functionFactory.arrayToString_hsql();`
`268`	`269`	`}`
`269`	`270`
`270`	`271`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -301,6 +301,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`301`	`301`	`functionFactory.arrayReplace_oracle();`
`302`	`302`	`functionFactory.arrayTrim_oracle();`
`303`	`303`	`functionFactory.arrayFill_oracle();`
	`304`	`+ functionFactory.arrayToString_oracle();`
`304`	`305`	`}`
`305`	`306`
`306`	`307`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -327,6 +327,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`327`	`327`	`functionFactory.arrayReplace_h2( getMaximumArraySize() );`
`328`	`328`	`functionFactory.arrayTrim_trim_array();`
`329`	`329`	`functionFactory.arrayFill_h2();`
	`330`	`+ functionFactory.arrayToString_h2( getMaximumArraySize() );`
`330`	`331`	`}`
`331`	`332`
`332`	`333`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -205,6 +205,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`205`	`205`	`functionFactory.arrayReplace_unnest();`
`206`	`206`	`functionFactory.arrayTrim_trim_array();`
`207`	`207`	`functionFactory.arrayFill_hsql();`
	`208`	`+ functionFactory.arrayToString_hsql();`
`208`	`209`	`}`
`209`	`210`
`210`	`211`	`@Override`