HHH-18496 Add json_query

Author: beikov

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

@@ -1633,6 +1633,7 @@ The following functions deal with SQL JSON types, which are not supported on eve
 | `json_array()` | Constructs a JSON array from arguments
 | `json_value()` | Extracts a value from a JSON document by JSON path
 | `json_exists()` | Checks if a JSON path exists in a JSON document
+| `json_query()` | Queries non-scalar values by JSON path in a JSON document
 |===
 
 
@@ -1712,7 +1713,7 @@ 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.
 
-WARNING: Some databases might also return non-scalar values. Beware that this behavior is not portable.
+WARNING: Some databases might also allow extracting non-scalar values. Beware that this behavior is not portable.
 
 NOTE: It is recommended to only us the dot notation for JSON paths instead of the bracket notation,
 since most databases support only that.
@@ -1832,6 +1833,92 @@ include::{json-example-dir-hql}/JsonExistsTest.java[tags=hql-json-exists-on-erro
 
 NOTE: The H2 emulation only supports absolute JSON paths using the dot notation.
 
+[[hql-json-query-function]]
+===== `json_query()`
+
+Queries non-scalar values from a JSON document by a https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html[JSON path].
+
+[[hql-json-query-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/json_query_bnf.txt[]
+----
+
+The first argument is an expression to a JSON document. The second argument is a JSON path as String expression.
+
+WARNING: Some databases might also allow querying scalar values. Beware that this behavior is not portable.
+
+NOTE: It is recommended to only us the dot notation for JSON paths instead of the bracket notation,
+since most databases support only that.
+
+[[hql-json-query-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonQueryTest.java[tags=hql-json-query-example]
+----
+====
+
+The `passing` clause allows to reuse the same JSON path but pass different values for evaluation.
+
+[[hql-json-query-passing-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonQueryTest.java[tags=hql-json-query-passing-example]
+----
+====
+
+The `wrapper` clause allows to specify whether results of a query should be wrapped in brackets `[]` i.e. an array.
+The default behavior is to omit an array wrapper i.e. `without wrapper`.
+It is an error when a `json_query` returns more than a single result and `without wrapper` is used.
+How an error like this should be handled can be controlled with the `on error` clause.
+
+WARNING: Since the default behavior of `on error` is database dependent,
+some databases might return a comma separated list of values even when using `without wrapper`. This is not portable.
+
+[[hql-json-query-wrapper-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonQueryTest.java[tags=hql-json-query-with-wrapper-example]
+----
+====
+
+The `on error` clause defines the behavior when an error occurs while querying with 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
+* Multiple `json_query` results when `without wrapper` is used
+
+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-query-on-error-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonQueryTest.java[tags=hql-json-query-on-error-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-query-on-empty-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonQueryTest.java[tags=hql-json-query-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_exists_bnf.txt

@@ -1,4 +1,4 @@
-"json_exists(" expression, expression passingClause? onErrorClause? ")"
+"json_exists(" expression "," expression passingClause? onErrorClause? ")"
 
 passingClause
 	: "passing" expression "as" identifier ("," expression "as" identifier)*

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

@@ -0,0 +1,14 @@
+"json_query(" expression "," expression passingClause? wrapperClause? onErrorClause? onEmptyClause? ")"
+
+wrapperClause
+	: "with" ("conditional"|"unconditional")? "array"? "wrapper"
+	| "without" "array"? "wrapper"
+
+passingClause
+	: "passing" expression "as" identifier ("," expression "as" identifier)*
+
+onErrorClause
+	: ( "error" | "null" | ( "empty" ( "array" | "object" )? ) ) "on error";
+
+onEmptyClause
+	: ( "error" | "null" | ( "empty" ( "array" | "object" )? ) ) "on empty";

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

@@ -1,4 +1,4 @@
-"json_value(" expression, expression passingClause? ("returning" castTarget)? onErrorClause? onEmptyClause? ")"
+"json_value(" expression "," expression passingClause? ("returning" castTarget)? onErrorClause? onEmptyClause? ")"
 
 passingClause
 	: "passing" expression "as" identifier ("," expression "as" identifier)*

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

@@ -433,6 +433,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 			if ( getDB2Version().isSameOrAfter( 11 ) ) {
 				functionFactory.jsonValue_no_passing();
+				functionFactory.jsonQuery_no_passing();
 				functionFactory.jsonExists_no_passing();
 				functionFactory.jsonObject_db2();
 				functionFactory.jsonArray_db2();

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

@@ -405,6 +405,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 				if ( getVersion().isSameOrAfter( 2, 2, 220 ) ) {
 					functionFactory.jsonValue_h2();
+					functionFactory.jsonQuery_h2();
 					functionFactory.jsonExists_h2();
 				}
 			}

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

@@ -656,6 +656,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		if ( getMySQLVersion().isSameOrAfter( 5, 7 ) ) {
 			functionFactory.jsonValue_mysql();
+			functionFactory.jsonQuery_mysql();
 			functionFactory.jsonExists_mysql();
 			functionFactory.jsonObject_mysql();
 			functionFactory.jsonArray_mysql();

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

@@ -325,6 +325,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		if ( getVersion().isSameOrAfter( 12 ) ) {
 			functionFactory.jsonValue_oracle();
+			functionFactory.jsonQuery_oracle();
 			functionFactory.jsonExists_oracle();
 			functionFactory.jsonObject_oracle();
 			functionFactory.jsonArray_oracle();

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

@@ -625,12 +625,14 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		if ( getVersion().isSameOrAfter( 17 ) ) {
 			functionFactory.jsonValue();
+			functionFactory.jsonQuery();
 			functionFactory.jsonExists();
 			functionFactory.jsonObject();
 			functionFactory.jsonArray();
 		}
 		else {
 			functionFactory.jsonValue_postgresql();
+			functionFactory.jsonQuery_postgresql();
 			functionFactory.jsonExists_postgresql();
 			if ( getVersion().isSameOrAfter( 16 ) ) {
 				functionFactory.jsonObject();

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

@@ -404,6 +404,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.hypotheticalOrderedSetAggregates_windowEmulation();
 		if ( getVersion().isSameOrAfter( 13 ) ) {
 			functionFactory.jsonValue_sqlserver();
+			functionFactory.jsonQuery_sqlserver();
 			functionFactory.jsonExists_sqlserver();
 			functionFactory.jsonObject_sqlserver();
 			functionFactory.jsonArray_sqlserver();