HHH-18604 Add json_mergepatch function

Author: beikov

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

@@ -1641,6 +1641,7 @@ it is necessary to enable the `hibernate.query.hql.json_functions_enabled` confi
 | `json_objectagg()` | Creates a JSON object by aggregating values
 | `json_set()` | Inserts/Replaces a value by JSON path within a JSON document
 | `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
 |===
 
 
@@ -2083,6 +2084,35 @@ include::{json-example-dir-hql}/JsonInsertTest.java[tags=hql-json-insert-example
 
 WARNING: SAP HANA, DB2, H2 and HSQLDB do not support this function.
 
+[[hql-json-mergepatch-function]]
+===== `json_mergepatch()`
+
+Merges JSON documents by performing an https://tools.ietf.org/html/rfc7396[RFC 7396] compliant merge, which is
+
+* When the first JSON value is not an object, the result is as if the first argument was an empty object
+* When the second JSON value is not an object, the result is the second argument
+* When both JSON values are objects, members are merged
+** Retain first JSON object members when the second JSON object has no members with matching keys
+** Retain second JSON object members when the first JSON object has no members with matching keys and the value is not equal to the JSON `null` literal
+** Recursively merge values that exist in both JSON objects, except if the second JSON object member is a JSON `null`
+
+In simple terms this means
+
+* The second JSON overrides members of the first, with JSON `null` values causing members to be removed
+* JSON objects are merged recursively
+
+NOTE: Arrays and hence objects within arrays are not merged, but replaced.
+
+[[hql-json-mergepatch-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonMergepatchTest.java[tags=hql-json-mergepatch-example]
+----
+====
+
+WARNING: SAP HANA, DB2, SQL Server, H2 and HSQLDB do not support this function. On PostgreSQL, this function is emulated.
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 

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

@@ -512,6 +512,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_cockroachdb();
 		functionFactory.jsonReplace_postgresql();
 		functionFactory.jsonInsert_postgresql();
+		functionFactory.jsonMergepatch_postgresql();
 
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )

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

@@ -664,6 +664,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonRemove_mysql();
 			functionFactory.jsonReplace_mysql();
 			functionFactory.jsonInsert_mysql();
+			functionFactory.jsonMergepatch_mysql();
 		}
 	}
 

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

@@ -321,6 +321,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonRemove_oracle();
 			functionFactory.jsonReplace_oracle();
 			functionFactory.jsonInsert_oracle();
+			functionFactory.jsonMergepatch_oracle();
 		}
 	}
 

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

@@ -662,6 +662,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_postgresql();
 		functionFactory.jsonReplace_postgresql();
 		functionFactory.jsonInsert_postgresql();
+		functionFactory.jsonMergepatch_postgresql();
 
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();

hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java

@@ -479,6 +479,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_cockroachdb();
 		functionFactory.jsonReplace_postgresql();
 		functionFactory.jsonInsert_postgresql();
+		functionFactory.jsonMergepatch_postgresql();
 
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )

hibernate-core/src/main/java/org/hibernate/dialect/MySQLDialect.java

@@ -649,6 +649,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_mysql();
 		functionFactory.jsonReplace_mysql();
 		functionFactory.jsonInsert_mysql();
+		functionFactory.jsonMergepatch_mysql();
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java

@@ -412,6 +412,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_oracle();
 		functionFactory.jsonReplace_oracle();
 		functionFactory.jsonInsert_oracle();
+		functionFactory.jsonMergepatch_oracle();
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java

@@ -623,6 +623,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.jsonRemove_postgresql();
 		functionFactory.jsonReplace_postgresql();
 		functionFactory.jsonInsert_postgresql();
+		functionFactory.jsonMergepatch_postgresql();
 
 		functionFactory.makeDateTimeTimestamp();
 		// Note that PostgreSQL doesn't support the OVER clause for ordered set-aggregate functions

hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java

@@ -97,10 +97,8 @@
 import org.hibernate.dialect.function.json.HSQLJsonArrayAggFunction;
 import org.hibernate.dialect.function.json.HSQLJsonArrayFunction;
 import org.hibernate.dialect.function.json.HSQLJsonObjectFunction;
-import org.hibernate.dialect.function.json.JsonArrayAggFunction;
 import org.hibernate.dialect.function.json.JsonArrayFunction;
 import org.hibernate.dialect.function.json.JsonExistsFunction;
-import org.hibernate.dialect.function.json.JsonObjectAggFunction;
 import org.hibernate.dialect.function.json.JsonObjectFunction;
 import org.hibernate.dialect.function.json.JsonQueryFunction;
 import org.hibernate.dialect.function.json.JsonValueFunction;
@@ -119,6 +117,7 @@
 import org.hibernate.dialect.function.json.OracleJsonArrayAggFunction;
 import org.hibernate.dialect.function.json.OracleJsonArrayFunction;
 import org.hibernate.dialect.function.json.OracleJsonInsertFunction;
+import org.hibernate.dialect.function.json.OracleJsonMergepatchFunction;
 import org.hibernate.dialect.function.json.OracleJsonObjectAggFunction;
 import org.hibernate.dialect.function.json.OracleJsonObjectFunction;
 import org.hibernate.dialect.function.json.OracleJsonRemoveFunction;
@@ -128,6 +127,7 @@
 import org.hibernate.dialect.function.json.PostgreSQLJsonArrayFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonExistsFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonInsertFunction;
+import org.hibernate.dialect.function.json.PostgreSQLJsonMergepatchFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonObjectAggFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonObjectFunction;
 import org.hibernate.dialect.function.json.PostgreSQLJsonQueryFunction;
@@ -3977,4 +3977,34 @@ public void jsonInsert_oracle() {
 	public void jsonInsert_sqlserver() {
 		functionRegistry.register( "json_insert", new SQLServerJsonInsertFunction( typeConfiguration ) );
 	}
+
+	/**
+	 * PostgreSQL json_mergepatch() function
+	 */
+	public void jsonMergepatch_postgresql() {
+		functionRegistry.register( "json_mergepatch", new PostgreSQLJsonMergepatchFunction( typeConfiguration ) );
+	}
+
+	/**
+	 * MySQL json_mergepatch() function
+	 */
+	public void jsonMergepatch_mysql() {
+		functionRegistry.namedDescriptorBuilder( "json_mergepatch", "json_merge_patch" )
+				.setArgumentsValidator( new ArgumentTypesValidator(
+						StandardArgumentsValidators.min( 2 ),
+						FunctionParameterType.IMPLICIT_JSON,
+						FunctionParameterType.IMPLICIT_JSON
+				) )
+				.setReturnTypeResolver( StandardFunctionReturnTypeResolvers.invariant(
+						typeConfiguration.getBasicTypeRegistry().resolve( String.class, SqlTypes.JSON )
+				) )
+				.register();
+	}
+
+	/**
+	 * Oracle json_mergepatch() function
+	 */
+	public void jsonMergepatch_oracle() {
+		functionRegistry.register( "json_mergepatch", new OracleJsonMergepatchFunction( typeConfiguration ) );
+	}
 }