HHH-18496 Add json_value function

Author: beikov

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

@@ -6,6 +6,7 @@
 :core-project-dir: {root-project-dir}/hibernate-core
 :example-dir-hql: {core-project-dir}/src/test/java/org/hibernate/orm/test/hql
 :array-example-dir-hql: {core-project-dir}/src/test/java/org/hibernate/orm/test/function/array
+:json-example-dir-hql: {core-project-dir}/src/test/java/org/hibernate/orm/test/function/json
 :extrasdir: extras
 
 This chapter describes Hibernate Query Language (HQL) and Jakarta Persistence Query Language (JPQL).
@@ -1619,6 +1620,85 @@ include::{array-example-dir-hql}/ArrayToStringTest.java[tags=hql-array-to-string
 ----
 ====
 
+[[hql-functions-json]]
+==== Functions for dealing with JSON
+
+The following functions deal with SQL JSON types, which are not supported on every database.
+
+[[hql-json-functions]]
+|===
+| Function | Purpose
+
+| `json_value()` | Extracts a value from a JSON document by JSON path
+|===
+
+[[hql-json-value-function]]
+===== `json_value()`
+
+Extracts a value by https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html[JSON path] from a JSON document.
+
+[[hql-like-json-value-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/json_value_bnf.txt[]
+----
+
+The first argument is an expression to a JSON document. The second argument is a JSON path as String expression.
+
+NOTE: It is recommended to only us the dot notation for JSON paths, since most databases support only that.
+
+[[hql-json-value-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-example]
+----
+====
+
+The `returning` clause allows to specify the <<hql-function-cast,cast target>> i.e. the type of value to extract.
+
+[[hql-json-value-returning-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-returning-example]
+----
+====
+
+The `on empty` clause defines the behavior when the JSON path does not match the JSON document.
+By default, `null` is returned on empty.
+
+[[hql-json-value-on-error-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-on-error-example]
+----
+====
+
+The `on error` clause defines the behavior when an error occurs while resolving the value for the JSON path.
+Conditions that classify as errors are database dependent, but usual errors which can be handled with this clause are:
+
+* First argument is not a valid JSON document
+* Second argument is not a valid JSON path
+* JSON path does not resolve to a scalar value
+
+The default behavior of `on error` is database specific, but usually, `null` is returned on an error.
+It is recommended to specify this clause when the exact error behavior is important.
+
+[[hql-json-value-on-empty-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-on-empty-example]
+----
+====
+
+To actually receive an error `on empty`, it is necessary to also specify `error on error`.
+Depending on the database, an error might still be thrown even without that, but that is not portable.
+
+NOTE: The H2 emulation only supports absolute JSON paths using the dot notation.
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 

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

@@ -0,0 +1,7 @@
+"json_value(" expression, expression ("returning" castTarget)? onErrorClause? onEmptyClause? ")"
+
+onErrorClause
+	: ( "error" | "null" | ( "default" expression ) ) "on error";
+
+onEmptyClause
+	: ( "error" | "null" | ( "default" expression ) ) "on empty";

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

@@ -492,6 +492,8 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayFill_cockroachdb();
 		functionFactory.arrayToString_postgresql();
 
+		functionFactory.jsonValue_cockroachdb();
+
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )
 				.setExactArgumentCount( 2 )

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

@@ -429,6 +429,10 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.windowFunctions();
 		if ( getDB2Version().isSameOrAfter( 9, 5 ) ) {
 			functionFactory.listagg( null );
+
+			if ( getDB2Version().isSameOrAfter( 11 ) ) {
+				functionFactory.jsonValue();
+			}
 		}
 	}
 

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

@@ -398,6 +398,10 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.arrayTrim_trim_array();
 				functionFactory.arrayFill_h2();
 				functionFactory.arrayToString_h2( getMaximumArraySize() );
+
+				if ( getVersion().isSameOrAfter( 2, 2, 220 ) ) {
+					functionFactory.jsonValue_h2();
+				}
 			}
 			else {
 				// Use group_concat until 2.x as listagg was buggy

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

@@ -89,6 +89,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 							.getBasicTypeRegistry()
 							.resolve( StandardBasicTypes.BOOLEAN )
 			);
+			commonFunctionFactory.jsonValue_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

@@ -651,6 +651,10 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionRegistry.registerAlternateKey( "char", "chr" );
 
 		functionFactory.listagg_groupConcat();
+
+		if ( getMySQLVersion().isSameOrAfter( 5, 7 ) ) {
+			functionFactory.jsonValue_mysql();
+		}
 	}
 
 	@Override

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

@@ -318,6 +318,10 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayTrim_oracle();
 		functionFactory.arrayFill_oracle();
 		functionFactory.arrayToString_oracle();
+
+		if ( getVersion().isSameOrAfter( 12 ) ) {
+			functionFactory.jsonValue_literal_path();
+		}
 	}
 
 	@Override

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

@@ -629,6 +629,13 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayFill_postgresql();
 		functionFactory.arrayToString_postgresql();
 
+		if ( getVersion().isSameOrAfter( 17 ) ) {
+			functionFactory.jsonValue();
+		}
+		else {
+			functionFactory.jsonValue_postgresql();
+		}
+
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();
 			// Note that PostgreSQL doesn't support the OVER clause for ordered set-aggregate functions

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

@@ -400,6 +400,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.windowFunctions();
 		functionFactory.inverseDistributionOrderedSetAggregates_windowEmulation();
 		functionFactory.hypotheticalOrderedSetAggregates_windowEmulation();
+		if ( getVersion().isSameOrAfter( 13 ) ) {
+			functionFactory.jsonValue_sqlserver();
+		}
 		if ( getVersion().isSameOrAfter( 14 ) ) {
 			functionFactory.listagg_stringAggWithinGroup( "varchar(max)" );
 		}