HHH-18496 Add json_exists and support the passing clause

Author: beikov

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

@@ -1632,6 +1632,7 @@ The following functions deal with SQL JSON types, which are not supported on eve
 | `json_object()` | Constructs a JSON object from pairs of key and value arguments
 | `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
 |===
 
 
@@ -1713,7 +1714,8 @@ The first argument is an expression to a JSON document. The second argument is a
 
 WARNING: Some databases might also return non-scalar values. Beware that this behavior is not portable.
 
-NOTE: It is recommended to only us the dot notation for JSON paths, since most databases support only that.
+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-value-example]]
 ====
@@ -1723,24 +1725,23 @@ 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.
+The `passing` clause allows to reuse the same JSON path but pass different values for evaluation.
 
-[[hql-json-value-returning-example]]
+[[hql-json-value-passing-example]]
 ====
 [source, java, indent=0]
 ----
-include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-returning-example]
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-passing-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.
+The `returning` clause allows to specify the <<hql-function-cast,cast target>> i.e. the type of value to extract.
 
-[[hql-json-value-on-error-example]]
+[[hql-json-value-returning-example]]
 ====
 [source, java, indent=0]
 ----
-include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-on-error-example]
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-returning-example]
 ----
 ====
 
@@ -1754,6 +1755,17 @@ Conditions that classify as errors are database dependent, but usual errors whic
 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-error-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonValueTest.java[tags=hql-json-value-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-value-on-empty-example]]
 ====
 [source, java, indent=0]
@@ -1767,6 +1779,59 @@ Depending on the database, an error might still be thrown even without that, but
 
 NOTE: The H2 emulation only supports absolute JSON paths using the dot notation.
 
+[[hql-json-exists-function]]
+===== `json_exists()`
+
+Checks if a JSON document contains a https://www.ietf.org/archive/id/draft-goessner-dispatch-jsonpath-00.html[JSON path].
+
+[[hql-json-exists-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/json_exists_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 instead of the bracket notation,
+since most databases support only that.
+
+[[hql-json-exists-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonExistsTest.java[tags=hql-json-exists-example]
+----
+====
+
+The `passing` clause allows to reuse the same JSON path but pass different values for evaluation.
+
+[[hql-json-exists-passing-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonExistsTest.java[tags=hql-json-exists-passing-example]
+----
+====
+
+The `on error` clause defines the behavior when an error occurs while checking for existence 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
+
+The default behavior of `on error` is database specific, but usually, `false` is returned on an error.
+It is recommended to specify this clause when the exact error behavior is important.
+
+[[hql-json-exists-on-error-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonExistsTest.java[tags=hql-json-exists-on-error-example]
+----
+====
+
+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

@@ -0,0 +1,7 @@
+"json_exists(" expression, expression passingClause? onErrorClause? ")"
+
+passingClause
+	: "passing" expression "as" identifier ("," expression "as" identifier)*
+
+onErrorClause
+	: ( "error" | "true" | "false" ) "on error";

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

@@ -1,4 +1,7 @@
-"json_value(" expression, expression ("returning" castTarget)? onErrorClause? onEmptyClause? ")"
+"json_value(" expression, expression passingClause? ("returning" castTarget)? onErrorClause? onEmptyClause? ")"
+
+passingClause
+	: "passing" expression "as" identifier ("," expression "as" identifier)*
 
 onErrorClause
 	: ( "error" | "null" | ( "default" expression ) ) "on error";

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

@@ -503,6 +503,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		functionFactory.jsonValue_cockroachdb();
 		functionFactory.jsonObject_postgresql();
+		functionFactory.jsonExists_postgresql();
 		functionFactory.jsonArray_postgresql();
 
 		// Postgres uses # instead of ^ for XOR

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

@@ -431,7 +431,8 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.listagg( null );
 
 			if ( getDB2Version().isSameOrAfter( 11 ) ) {
-				functionFactory.jsonValue();
+				functionFactory.jsonValue_no_passing();
+				functionFactory.jsonExists_no_passing();
 				functionFactory.jsonObject_db2();
 				functionFactory.jsonArray_db2();
 			}

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

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

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

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

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

@@ -322,7 +322,8 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayToString_oracle();
 
 		if ( getVersion().isSameOrAfter( 12 ) ) {
-			functionFactory.jsonValue_literal_path();
+			functionFactory.jsonValue_oracle();
+			functionFactory.jsonExists_oracle();
 			functionFactory.jsonObject_oracle();
 			functionFactory.jsonArray_oracle();
 		}

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

@@ -634,11 +634,13 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		if ( getVersion().isSameOrAfter( 17 ) ) {
 			functionFactory.jsonValue();
+			functionFactory.jsonExists();
 			functionFactory.jsonObject();
 			functionFactory.jsonArray();
 		}
 		else {
 			functionFactory.jsonValue_postgresql();
+			functionFactory.jsonExists_postgresql();
 			if ( getVersion().isSameOrAfter( 16 ) ) {
 				functionFactory.jsonObject();
 				functionFactory.jsonArray();

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

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