HHH-18604 Add json_array_insert

beikov · beikov · commit 43b49b7c410b · 2024-09-18T12:40:55.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
@@ -1643,6 +1643,7 @@ it is necessary to enable the `hibernate.query.hql.json_functions_enabled` confi
 | `json_remove()` | Removes a value by JSON path within a JSON document
 | `json_mergepatch()` | Merges JSON documents by performing an https://tools.ietf.org/html/rfc7396[RFC 7396] compliant merge
 | `json_array_append()` | Appends to a JSON array of a JSON document by JSON path
+| `json_array_insert()` | Inserts a value by JSON path to a JSON array within a JSON document
 |===
 
 
@@ -2134,6 +2135,29 @@ include::{json-example-dir-hql}/JsonArrayAppendTest.java[tags=hql-json-array-app
 
 WARNING: SAP HANA, DB2, H2 and HSQLDB do not support this function.
 
+[[hql-json-array-insert-function]]
+===== `json_array_insert()`
+
+Inserts a value by JSON path to a JSON array within a JSON document.
+The function takes 3 arguments, the json document, the json path and the value to append.
+
+Although the exact behavior is database dependent, usually an error will be triggered if
+the JSON path does not end with an array index access i.e. `$.a[0]`.
+The zero based array index represents the position at which an element should be inserted in an array.
+
+If the JSON path without the index does not resolve to a JSON array within the JSON document,
+the document is not changed.
+
+[[hql-json-array-insert-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonArrayInsertTest.java[tags=hql-json-array-insert-example]
+----
+====
+
+WARNING: SAP HANA, DB2, H2 and HSQLDB do not support this function.
+
 [[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
@@ -514,6 +514,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_postgresql();
 		functionFactory.jsonMergepatch_postgresql();
 		functionFactory.jsonArrayAppend_postgresql();
+		functionFactory.jsonArrayInsert_postgresql();
 
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/MySQLLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/MySQLLegacyDialect.java
@@ -666,6 +666,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonInsert_mysql();
 			functionFactory.jsonMergepatch_mysql();
 			functionFactory.jsonArrayAppend_mysql();
+			functionFactory.jsonArrayInsert_mysql();
 		}
 	}
 
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
@@ -323,6 +323,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonInsert_oracle();
 			functionFactory.jsonMergepatch_oracle();
 			functionFactory.jsonArrayAppend_oracle();
+			functionFactory.jsonArrayInsert_oracle();
 		}
 	}
 
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
@@ -653,6 +653,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_postgresql();
 		functionFactory.jsonMergepatch_postgresql();
 		functionFactory.jsonArrayAppend_postgresql();
+		functionFactory.jsonArrayInsert_postgresql();
 
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();
diff --git a/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/SQLServerLegacyDialect.java b/hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/SQLServerLegacyDialect.java
@@ -411,6 +411,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonReplace_sqlserver();
 			functionFactory.jsonInsert_sqlserver();
 			functionFactory.jsonArrayAppend_sqlserver();
+			functionFactory.jsonArrayInsert_sqlserver();
 		}
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java
@@ -481,6 +481,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_postgresql();
 		functionFactory.jsonMergepatch_postgresql();
 		functionFactory.jsonArrayAppend_postgresql();
+		functionFactory.jsonArrayInsert_postgresql();
 
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/MySQLDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/MySQLDialect.java
@@ -651,6 +651,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_mysql();
 		functionFactory.jsonMergepatch_mysql();
 		functionFactory.jsonArrayAppend_mysql();
+		functionFactory.jsonArrayInsert_mysql();
 	}
 
 	@Override
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java
@@ -414,6 +414,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_oracle();
 		functionFactory.jsonMergepatch_oracle();
 		functionFactory.jsonArrayAppend_oracle();
+		functionFactory.jsonArrayInsert_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
@@ -614,6 +614,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonInsert_postgresql();
 		functionFactory.jsonMergepatch_postgresql();
 		functionFactory.jsonArrayAppend_postgresql();
+		functionFactory.jsonArrayInsert_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/SQLServerDialect.java b/hibernate-core/src/main/java/org/hibernate/dialect/SQLServerDialect.java
@@ -429,6 +429,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonReplace_sqlserver();
 			functionFactory.jsonInsert_sqlserver();
 			functionFactory.jsonArrayAppend_sqlserver();
+			functionFactory.jsonArrayInsert_sqlserver();
 		}
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
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
@@ -118,6 +118,7 @@
 import org.hibernate.dialect.function.json.OracleJsonArrayAggFunction;
 import org.hibernate.dialect.function.json.OracleJsonArrayAppendFunction;
 import org.hibernate.dialect.function.json.OracleJsonArrayFunction;
+import org.hibernate.dialect.function.json.OracleJsonArrayInsertFunction;
 import org.hibernate.dialect.function.json.OracleJsonInsertFunction;
 import org.hibernate.dialect.function.json.OracleJsonMergepatchFunction;
 import org.hibernate.dialect.function.json.OracleJsonObjectAggFunction;
@@ -128,6 +129,7 @@
 import org.hibernate.dialect.function.json.PostgreSQLJsonArrayAggFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonArrayAppendFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonArrayFunction;
+import org.hibernate.dialect.function.json.PostgreSQLJsonArrayInsertFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonExistsFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonInsertFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonMergepatchFunction;
@@ -141,6 +143,7 @@
 import org.hibernate.dialect.function.json.SQLServerJsonArrayAggFunction;
 import org.hibernate.dialect.function.json.SQLServerJsonArrayAppendFunction;
 import org.hibernate.dialect.function.json.SQLServerJsonArrayFunction;
+import org.hibernate.dialect.function.json.SQLServerJsonArrayInsertFunction;
 import org.hibernate.dialect.function.json.SQLServerJsonExistsFunction;
 import org.hibernate.dialect.function.json.SQLServerJsonInsertFunction;
 import org.hibernate.dialect.function.json.SQLServerJsonObjectAggFunction;
@@ -4056,4 +4059,42 @@ public void jsonArrayAppend_oracle() {
 	public void jsonArrayAppend_sqlserver() {
 		functionRegistry.register( "json_array_append", new SQLServerJsonArrayAppendFunction( typeConfiguration ) );
 	}
+
+	/**
+	 * PostgreSQL json_array_insert() function
+	 */
+	public void jsonArrayInsert_postgresql() {
+		functionRegistry.register( "json_array_insert", new PostgreSQLJsonArrayInsertFunction( typeConfiguration ) );
+	}
+
+	/**
+	 * MySQL json_array_insert() function
+	 */
+	public void jsonArrayInsert_mysql() {
+		functionRegistry.namedDescriptorBuilder( "json_array_insert" )
+				.setArgumentsValidator( new ArgumentTypesValidator(
+						StandardArgumentsValidators.exactly( 3 ),
+						FunctionParameterType.IMPLICIT_JSON,
+						FunctionParameterType.STRING,
+						FunctionParameterType.ANY
+				) )
+				.setReturnTypeResolver( StandardFunctionReturnTypeResolvers.invariant(
+						typeConfiguration.getBasicTypeRegistry().resolve( String.class, SqlTypes.JSON )
+				) )
+				.register();
+	}
+
+	/**
+	 * Oracle json_array_insert() function
+	 */
+	public void jsonArrayInsert_oracle() {
+		functionRegistry.register( "json_array_insert", new OracleJsonArrayInsertFunction( typeConfiguration ) );
+	}
+
+	/**
+	 * SQL server json_array_insert() function
+	 */
+	public void jsonArrayInsert_sqlserver() {
+		functionRegistry.register( "json_array_insert", new SQLServerJsonArrayInsertFunction( typeConfiguration ) );
+	}
 }
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/json/AbstractJsonArrayInsertFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/json/AbstractJsonArrayInsertFunction.java
@@ -0,0 +1,38 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.dialect.function.json;
+
+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.FunctionParameterType;
+import org.hibernate.query.sqm.produce.function.StandardArgumentsValidators;
+import org.hibernate.query.sqm.produce.function.StandardFunctionReturnTypeResolvers;
+import org.hibernate.type.SqlTypes;
+import org.hibernate.type.spi.TypeConfiguration;
+
+/**
+ * Standard json_array_insert function.
+ */
+public abstract class AbstractJsonArrayInsertFunction extends AbstractSqmSelfRenderingFunctionDescriptor {
+
+	public AbstractJsonArrayInsertFunction(TypeConfiguration typeConfiguration) {
+		super(
+				"json_array_insert",
+				FunctionKind.NORMAL,
+				new ArgumentTypesValidator(
+						StandardArgumentsValidators.exactly( 3 ),
+						FunctionParameterType.IMPLICIT_JSON,
+						FunctionParameterType.STRING,
+						FunctionParameterType.ANY
+				),
+				StandardFunctionReturnTypeResolvers.invariant(
+						typeConfiguration.getBasicTypeRegistry().resolve( String.class, SqlTypes.JSON )
+				),
+				null
+		);
+	}
+
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/json/OracleJsonArrayInsertFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/json/OracleJsonArrayInsertFunction.java
@@ -0,0 +1,43 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.dialect.function.json;
+
+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;
+
+/**
+ * Oracle json_array_insert function.
+ */
+public class OracleJsonArrayInsertFunction extends AbstractJsonArrayInsertFunction {
+
+	public OracleJsonArrayInsertFunction(TypeConfiguration typeConfiguration) {
+		super( typeConfiguration );
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> arguments,
+			ReturnableType<?> returnType,
+			SqlAstTranslator<?> translator) {
+		final Expression json = (Expression) arguments.get( 0 );
+		final String jsonPath = translator.getLiteralValue( (Expression) arguments.get( 1 ) );
+		final SqlAstNode value = arguments.get( 2 );
+		sqlAppender.appendSql( "json_transform(" );
+		json.accept( translator );
+		sqlAppender.appendSql( ",insert " );
+		sqlAppender.appendSingleQuoteEscapedString( jsonPath );
+		sqlAppender.appendSql( '=' );
+		value.accept( translator );
+		sqlAppender.appendSql( " ignore on existing)" );
+
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/json/PostgreSQLJsonArrayInsertFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/json/PostgreSQLJsonArrayInsertFunction.java
@@ -0,0 +1,87 @@
+/*
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ * Copyright Red Hat Inc. and Hibernate Authors
+ */
+package org.hibernate.dialect.function.json;
+
+import java.util.List;
+
+import org.hibernate.QueryException;
+import org.hibernate.metamodel.mapping.JdbcMappingContainer;
+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.sql.ast.tree.expression.Literal;
+import org.hibernate.type.spi.TypeConfiguration;
+
+/**
+ * PostgreSQL json_array_insert function.
+ */
+public class PostgreSQLJsonArrayInsertFunction extends AbstractJsonArrayInsertFunction {
+
+	public PostgreSQLJsonArrayInsertFunction(TypeConfiguration typeConfiguration) {
+		super( typeConfiguration );
+	}
+
+	@Override
+	public void render(
+			SqlAppender sqlAppender,
+			List<? extends SqlAstNode> arguments,
+			ReturnableType<?> returnType,
+			SqlAstTranslator<?> translator) {
+		final Expression json = (Expression) arguments.get( 0 );
+		final Expression jsonPath = (Expression) arguments.get( 1 );
+		final SqlAstNode value = arguments.get( 2 );
+		sqlAppender.appendSql( "jsonb_insert(" );
+		final boolean needsCast = !isJsonType( json );
+		if ( needsCast ) {
+			sqlAppender.appendSql( "cast(" );
+		}
+		json.accept( translator );
+		if ( needsCast ) {
+			sqlAppender.appendSql( " as jsonb)" );
+		}
+		sqlAppender.appendSql( ',' );
+		List<JsonPathHelper.JsonPathElement> jsonPathElements =
+				JsonPathHelper.parseJsonPathElements( translator.getLiteralValue( jsonPath ) );
+		sqlAppender.appendSql( "array" );
+		char separator = '[';
+		for ( JsonPathHelper.JsonPathElement pathElement : jsonPathElements ) {
+			sqlAppender.appendSql( separator );
+			if ( pathElement instanceof JsonPathHelper.JsonAttribute attribute ) {
+				sqlAppender.appendSingleQuoteEscapedString( attribute.attribute() );
+			}
+			else if ( pathElement instanceof JsonPathHelper.JsonParameterIndexAccess ) {
+				final String parameterName = ( (JsonPathHelper.JsonParameterIndexAccess) pathElement ).parameterName();
+				throw new QueryException( "JSON path [" + jsonPath + "] uses parameter [" + parameterName + "] that is not passed" );
+			}
+			else {
+				sqlAppender.appendSql( '\'' );
+				sqlAppender.appendSql( ( (JsonPathHelper.JsonIndexAccess) pathElement ).index() );
+				sqlAppender.appendSql( '\'' );
+			}
+			separator = ',';
+		}
+		sqlAppender.appendSql( "]::text[]," );
+		if ( value instanceof Literal && ( (Literal) value ).getLiteralValue() == null ) {
+			sqlAppender.appendSql( "null::jsonb" );
+		}
+		else {
+			sqlAppender.appendSql( "to_jsonb(" );
+			value.accept( translator );
+			if ( value instanceof Literal literal && literal.getJdbcMapping().getJdbcType().isString() ) {
+				// PostgreSQL until version 16 is not smart enough to infer the type of a string literal
+				sqlAppender.appendSql( "::text" );
+			}
+			sqlAppender.appendSql( ')' );
+		}
+		sqlAppender.appendSql( ')' );
+	}
+
+	private static boolean isJsonType(Expression expression) {
+		final JdbcMappingContainer expressionType = expression.getExpressionType();
+		return expressionType != null && expressionType.getSingleJdbcMapping().getJdbcType().isJson();
+	}
+}
diff --git a/hibernate-core/src/main/java/org/hibernate/dialect/function/json/SQLServerJsonArrayInsertFunction.java b/hibernate-core/src/main/java/org/hibernate/dialect/function/json/SQLServerJsonArrayInsertFunction.java
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/function/json/JsonArrayInsertTest.java b/hibernate-core/src/test/java/org/hibernate/orm/test/function/json/JsonArrayInsertTest.java
diff --git a/hibernate-core/src/test/java/org/hibernate/orm/test/query/hql/JsonFunctionTests.java b/hibernate-core/src/test/java/org/hibernate/orm/test/query/hql/JsonFunctionTests.java
diff --git a/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/DialectFeatureChecks.java b/hibernate-testing/src/main/java/org/hibernate/testing/orm/junit/DialectFeatureChecks.java

Original file line number	Diff line number	Diff line change
`@@ -666,6 +666,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`666`	`666`	`functionFactory.jsonInsert_mysql();`
`667`	`667`	`functionFactory.jsonMergepatch_mysql();`
`668`	`668`	`functionFactory.jsonArrayAppend_mysql();`
	`669`	`+ functionFactory.jsonArrayInsert_mysql();`
`669`	`670`	`}`
`670`	`671`	`}`
`671`	`672`
Original file line number	Diff line number	Diff line change
`@@ -323,6 +323,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`323`	`323`	`functionFactory.jsonInsert_oracle();`
`324`	`324`	`functionFactory.jsonMergepatch_oracle();`
`325`	`325`	`functionFactory.jsonArrayAppend_oracle();`
	`326`	`+ functionFactory.jsonArrayInsert_oracle();`
`326`	`327`	`}`
`327`	`328`	`}`
`328`	`329`
Original file line number	Diff line number	Diff line change
`@@ -411,6 +411,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`411`	`411`	`functionFactory.jsonReplace_sqlserver();`
`412`	`412`	`functionFactory.jsonInsert_sqlserver();`
`413`	`413`	`functionFactory.jsonArrayAppend_sqlserver();`
	`414`	`+ functionFactory.jsonArrayInsert_sqlserver();`
`414`	`415`	`}`
`415`	`416`	`if ( getVersion().isSameOrAfter( 14 ) ) {`
`416`	`417`	`functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );`
Original file line number	Diff line number	Diff line change
`@@ -651,6 +651,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`651`	`651`	`functionFactory.jsonInsert_mysql();`
`652`	`652`	`functionFactory.jsonMergepatch_mysql();`
`653`	`653`	`functionFactory.jsonArrayAppend_mysql();`
	`654`	`+ functionFactory.jsonArrayInsert_mysql();`
`654`	`655`	`}`
`655`	`656`
`656`	`657`	`@Override`
Original file line number	Diff line number	Diff line change
`@@ -414,6 +414,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio`
`414`	`414`	`functionFactory.jsonInsert_oracle();`
`415`	`415`	`functionFactory.jsonMergepatch_oracle();`
`416`	`416`	`functionFactory.jsonArrayAppend_oracle();`
	`417`	`+ functionFactory.jsonArrayInsert_oracle();`
`417`	`418`	`}`
`418`	`419`
`419`	`420`	`@Override`