HHH-17335 Add array_replace function

beikov · beikov · commit 24fa18f95446 · 2023-10-25T18:58:44.000+02: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
@@ -1131,6 +1131,7 @@ The following functions deal with SQL array types, which are not supported on ev
 | `array_set()` | Creates array copy with given element at given index
 | `array_remove()` | Creates array copy with given element removed
 | `array_slice()` | Creates a sub-array of the based on lower and upper index
+| `array_replace()` | Creates array copy replacing a given element with another
 |===
 
 ===== `array()`
@@ -1316,6 +1317,19 @@ include::{array-example-dir-hql}/ArrayRemoveIndexTest.java[tags=hql-array-remove
 ----
 ====
 
+[[hql-array-replace-functions]]
+===== `array_replace()`
+
+Returns an array copy which has elements matching the second argument replaced by the third argument.
+
+[[hql-array-replace-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{array-example-dir-hql}/ArrayReplaceTest.java[tags=hql-array-replace-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
@@ -477,6 +477,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove();
 		functionFactory.arrayRemoveIndex_unnest( true );
 		functionFactory.arraySlice_operator();
+		functionFactory.arrayReplace();
 
 		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
@@ -385,6 +385,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.arrayRemove_h2();
 				functionFactory.arrayRemoveIndex_h2();
 				functionFactory.arraySlice();
+				functionFactory.arrayReplace_h2();
 			}
 			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
@@ -263,6 +263,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove_hsql();
 		functionFactory.arrayRemoveIndex_unnest( false );
 		functionFactory.arraySlice_unnest();
+		functionFactory.arrayReplace_unnest();
 	}
 
 	@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
@@ -299,6 +299,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove_oracle();
 		functionFactory.arrayRemoveIndex_oracle();
 		functionFactory.arraySlice_oracle();
+		functionFactory.arrayReplace_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
@@ -597,6 +597,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove();
 		functionFactory.arrayRemoveIndex_unnest( true );
 		functionFactory.arraySlice_operator();
+		functionFactory.arrayReplace();
 
 		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
@@ -464,6 +464,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove();
 		functionFactory.arrayRemoveIndex_unnest( true );
 		functionFactory.arraySlice_operator();
+		functionFactory.arrayReplace();
 
 		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
@@ -324,6 +324,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove_h2();
 		functionFactory.arrayRemoveIndex_h2();
 		functionFactory.arraySlice();
+		functionFactory.arrayReplace_h2();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/HSQLDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/HSQLDialect.java
@@ -203,6 +203,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove_hsql();
 		functionFactory.arrayRemoveIndex_unnest( false );
 		functionFactory.arraySlice_unnest();
+		functionFactory.arrayReplace_unnest();
 	}
 
 	@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
@@ -439,6 +439,38 @@ public void addAuxiliaryDatabaseObjects(
 						false
 				)
 		);
+		database.addAuxiliaryDatabaseObject(
+				new NamedAuxiliaryDatabaseObject(
+						arrayTypeName + "_replace",
+						database.getDefaultNamespace(),
+						new String[]{
+								"create or replace function " + arrayTypeName + "_replace(arr in " + arrayTypeName +
+										", old in " + getRawTypeName( elementType ) + ", elem in " + getRawTypeName( elementType ) + ") return " + arrayTypeName + " deterministic is " +
+										"res " + arrayTypeName + ":=" + arrayTypeName + "(); begin " +
+										"if arr is null then return null; end if; " +
+										"if old is null then " +
+										"for i in 1 .. arr.count loop " +
+										"res.extend; " +
+										"res(res.last) := coalesce(arr(i),elem); " +
+										"end loop; " +
+										"else " +
+										"for i in 1 .. arr.count loop " +
+										"res.extend; " +
+										"if arr(i) = old then " +
+										"res(res.last) := elem; " +
+										"else " +
+										"res(res.last) := arr(i); " +
+										"end if; " +
+										"end loop; " +
+										"end if; " +
+										"return res; " +
+										"end;"
+						},
+						new String[] { "drop function " + arrayTypeName + "_replace" },
+						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
@@ -328,6 +328,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove_oracle();
 		functionFactory.arrayRemoveIndex_oracle();
 		functionFactory.arraySlice_oracle();
+		functionFactory.arrayReplace_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
@@ -645,6 +645,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayRemove();
 		functionFactory.arrayRemoveIndex_unnest( true );
 		functionFactory.arraySlice_operator();
+		functionFactory.arrayReplace();
 
 		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
@@ -23,13 +23,15 @@
 import org.hibernate.dialect.function.array.ArrayContainsQuantifiedUnnestFunction;
 import org.hibernate.dialect.function.array.ArrayGetUnnestFunction;
 import org.hibernate.dialect.function.array.ArrayRemoveIndexUnnestFunction;
+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.ArrayViaArgumentReturnTypeResolver;
 import org.hibernate.dialect.function.array.ElementViaArrayArgumentReturnTypeResolver;
 import org.hibernate.dialect.function.array.H2ArrayContainsQuantifiedEmulation;
 import org.hibernate.dialect.function.array.H2ArrayRemoveFunction;
 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.HSQLArrayPositionFunction;
 import org.hibernate.dialect.function.array.HSQLArrayRemoveFunction;
@@ -42,6 +44,7 @@
 import org.hibernate.dialect.function.array.OracleArrayPositionFunction;
 import org.hibernate.dialect.function.array.OracleArrayRemoveFunction;
 import org.hibernate.dialect.function.array.OracleArrayRemoveIndexFunction;
+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.PostgreSQLArrayConcatFunction;
@@ -3133,4 +3136,42 @@ public void arraySlice_operator() {
 	public void arraySlice_oracle() {
 		functionRegistry.register( "array_slice", new OracleArraySliceFunction() );
 	}
+
+	/**
+	 * H2 array_replace() function
+	 */
+	public void arrayReplace_h2() {
+		functionRegistry.register( "array_replace", new H2ArrayReplaceFunction() );
+	}
+
+	/**
+	 * HSQL array_replace() function
+	 */
+	public void arrayReplace_unnest() {
+		functionRegistry.register( "array_replace", new ArrayReplaceUnnestFunction() );
+	}
+
+	/**
+	 * CockroachDB and PostgreSQL array_replace() function
+	 */
+	public void arrayReplace() {
+		functionRegistry.namedDescriptorBuilder( "array_replace" )
+				.setArgumentsValidator(
+						StandardArgumentsValidators.composite(
+								StandardArgumentsValidators.exactly( 3 ),
+								new ArrayAndElementArgumentValidator( 0, 1, 2 )
+						)
+				)
+				.setReturnTypeResolver( ArrayViaArgumentReturnTypeResolver.DEFAULT_INSTANCE )
+				.setArgumentTypeResolver( new ArrayAndElementArgumentTypeResolver( 0, 1, 2 ) )
+				.setArgumentListSignature( "(ARRAY array, OBJECT old, OBJECT new)" )
+				.register();
+	}
+
+	/**
+	 * Oracle array_replace() function
+	 */
+	public void arrayReplace_oracle() {
+		functionRegistry.register( "array_replace", new OracleArrayReplaceFunction() );
+	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayAndElementArgumentTypeResolver.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayAndElementArgumentTypeResolver.java
@@ -6,6 +6,7 @@
  */
 package org.hibernate.dialect.function.array;
 
+import org.hibernate.internal.util.collections.ArrayHelper;
 import org.hibernate.metamodel.mapping.MappingModelExpressible;
 import org.hibernate.metamodel.model.domain.DomainType;
 import org.hibernate.query.ReturnableType;
@@ -25,11 +26,11 @@ public class ArrayAndElementArgumentTypeResolver implements FunctionArgumentType
 	public static final FunctionArgumentTypeResolver DEFAULT_INSTANCE = new ArrayAndElementArgumentTypeResolver( 0, 1 );
 
 	private final int arrayIndex;
-	private final int elementIndex;
+	private final int[] elementIndexes;
 
-	public ArrayAndElementArgumentTypeResolver(int arrayIndex, int elementIndex) {
+	public ArrayAndElementArgumentTypeResolver(int arrayIndex, int... elementIndexes) {
 		this.arrayIndex = arrayIndex;
-		this.elementIndex = elementIndex;
+		this.elementIndexes = elementIndexes;
 	}
 
 	@Override
@@ -38,16 +39,18 @@ public MappingModelExpressible<?> resolveFunctionArgumentType(
 			int argumentIndex,
 			SqmToSqlAstConverter converter) {
 		if ( argumentIndex == arrayIndex ) {
-			final SqmTypedNode<?> argument = function.getArguments().get( elementIndex );
-			final DomainType<?> sqmType = argument.getExpressible().getSqmType();
-			if ( sqmType instanceof ReturnableType<?> ) {
-				return ArrayTypeHelper.resolveArrayType(
-						sqmType,
-						converter.getCreationContext().getSessionFactory().getTypeConfiguration()
-				);
+			for ( int elementIndex : elementIndexes ) {
+				final SqmTypedNode<?> argument = function.getArguments().get( elementIndex );
+				final DomainType<?> sqmType = argument.getExpressible().getSqmType();
+				if ( sqmType instanceof ReturnableType<?> ) {
+					return ArrayTypeHelper.resolveArrayType(
+							sqmType,
+							converter.getCreationContext().getSessionFactory().getTypeConfiguration()
+					);
+				}
 			}
 		}
-		else if ( argumentIndex == elementIndex ) {
+		else if ( ArrayHelper.contains( elementIndexes, argumentIndex ) ) {
 			final SqmTypedNode<?> argument = function.getArguments().get( arrayIndex );
 			final SqmExpressible<?> sqmType = argument.getNodeType();
 			if ( sqmType instanceof BasicPluralType<?, ?> ) {
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayAndElementArgumentValidator.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayAndElementArgumentValidator.java
@@ -22,11 +22,11 @@ public class ArrayAndElementArgumentValidator extends ArrayArgumentValidator {
 
 	public static final ArgumentsValidator DEFAULT_INSTANCE = new ArrayAndElementArgumentValidator( 0, 1 );
 
-	private final int elementIndex;
+	private final int[] elementIndexes;
 
-	public ArrayAndElementArgumentValidator(int arrayIndex, int elementIndex) {
+	public ArrayAndElementArgumentValidator(int arrayIndex, int... elementIndexes) {
 		super( arrayIndex );
-		this.elementIndex = elementIndex;
+		this.elementIndexes = elementIndexes;
 	}
 
 	@Override
@@ -35,18 +35,20 @@ public void validate(
 			String functionName,
 			TypeConfiguration typeConfiguration) {
 		final BasicType<?> expectedElementType = getElementType( arguments, functionName, typeConfiguration );
-		final SqmTypedNode<?> elementArgument = arguments.get( elementIndex );
-		final SqmExpressible<?> elementType = elementArgument.getExpressible().getSqmType();
-		if ( expectedElementType != null && elementType != null && expectedElementType != elementType ) {
-			throw new FunctionArgumentException(
-					String.format(
-							"Parameter %d of function '%s()' has type %s, but argument is of type '%s'",
-							elementIndex,
-							functionName,
-							expectedElementType.getJavaTypeDescriptor().getTypeName(),
-							elementType.getTypeName()
-					)
-			);
+		for ( int elementIndex : elementIndexes ) {
+			final SqmTypedNode<?> elementArgument = arguments.get( elementIndex );
+			final SqmExpressible<?> elementType = elementArgument.getExpressible().getSqmType();
+			if ( expectedElementType != null && elementType != null && expectedElementType != elementType ) {
+				throw new FunctionArgumentException(
+						String.format(
+								"Parameter %d of function '%s()' has type %s, but argument is of type '%s'",
+								elementIndex,
+								functionName,
+								expectedElementType.getJavaTypeDescriptor().getTypeName(),
+								elementType.getTypeName()
+						)
+				);
+			}
 		}
 	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayReplaceUnnestFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/ArrayReplaceUnnestFunction.java
@@ -0,0 +1,53 @@
+/*
+ * 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.sqm.function.AbstractSqmSelfRenderingFunctionDescriptor;
+import org.hibernate.query.sqm.produce.function.StandardArgumentsValidators;
+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;
+
+/**
+ * Implement the array replace function by using {@code unnest}.
+ */
+public class ArrayReplaceUnnestFunction extends AbstractSqmSelfRenderingFunctionDescriptor {
+
+	public ArrayReplaceUnnestFunction() {
+		super(
+				"array_replace",
+				StandardArgumentsValidators.composite(
+						StandardArgumentsValidators.exactly( 3 ),
+						new ArrayAndElementArgumentValidator( 0, 1, 2 )
+				),
+				ArrayViaArgumentReturnTypeResolver.DEFAULT_INSTANCE,
+				new ArrayAndElementArgumentTypeResolver( 0, 1, 2 )
+		);
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> sqlAstArguments,
+			SqlAstTranslator<?> walker) {
+		final Expression arrayExpression = (Expression) sqlAstArguments.get( 0 );
+		final Expression oldExpression = (Expression) sqlAstArguments.get( 1 );
+		final Expression newExpression = (Expression) sqlAstArguments.get( 2 );
+		sqlAppender.append( "case when ");
+		arrayExpression.accept( walker );
+		sqlAppender.append( " is null then null else coalesce((select array_agg(case when t.val is not distinct from " );
+		oldExpression.accept( walker );
+		sqlAppender.append( " then " );
+		newExpression.accept( walker );
+		sqlAppender.append( " else t.val end) from unnest(" );
+		arrayExpression.accept( walker );
+		sqlAppender.append( ") t(val)),array[]) end" );
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/H2ArrayReplaceFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/H2ArrayReplaceFunction.java
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/array/OracleArrayReplaceFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/array/OracleArrayReplaceFunction.java
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayReplaceTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/function/array/ArrayReplaceTest.java

Original file line number	Diff line number	Diff line change
`@@ -385,6 +385,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`385`	`385`	`functionFactory.arrayRemove_h2();`
`386`	`386`	`functionFactory.arrayRemoveIndex_h2();`
`387`	`387`	`functionFactory.arraySlice();`
	`388`	`+ functionFactory.arrayReplace_h2();`
`388`	`389`	`}`
`389`	`390`	`else {`
`390`	`391`	`// Use group_concat until 2.x as listagg was buggy`
Original file line number	Diff line number	Diff line change
`@@ -263,6 +263,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`263`	`263`	`functionFactory.arrayRemove_hsql();`
`264`	`264`	`functionFactory.arrayRemoveIndex_unnest( false );`
`265`	`265`	`functionFactory.arraySlice_unnest();`
	`266`	`+ functionFactory.arrayReplace_unnest();`
`266`	`267`	`}`
`267`	`268`
`268`	`269`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -299,6 +299,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`299`	`299`	`functionFactory.arrayRemove_oracle();`
`300`	`300`	`functionFactory.arrayRemoveIndex_oracle();`
`301`	`301`	`functionFactory.arraySlice_oracle();`
	`302`	`+ functionFactory.arrayReplace_oracle();`
`302`	`303`	`}`
`303`	`304`
`304`	`305`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -324,6 +324,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`324`	`324`	`functionFactory.arrayRemove_h2();`
`325`	`325`	`functionFactory.arrayRemoveIndex_h2();`
`326`	`326`	`functionFactory.arraySlice();`
	`327`	`+ functionFactory.arrayReplace_h2();`
`327`	`328`	`}`
`328`	`329`
`329`	`330`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -203,6 +203,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`203`	`203`	`functionFactory.arrayRemove_hsql();`
`204`	`204`	`functionFactory.arrayRemoveIndex_unnest( false );`
`205`	`205`	`functionFactory.arraySlice_unnest();`
	`206`	`+ functionFactory.arrayReplace_unnest();`
`206`	`207`	`}`
`207`	`208`
`208`	`209`	`@Override`