HHH-18758 Add json_table() set-returning function

Author: beikov

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

@@ -1677,18 +1677,19 @@ it is necessary to enable the `hibernate.query.hql.json_functions_enabled` confi
 |===
 | Function | Purpose
 
-| `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
-| `json_query()` | Queries non-scalar values by JSON path in a JSON document
-| `json_arrayagg()` | Creates a JSON array by aggregating values
-| `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
-| `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
+| <<hql-json-object-function,`json_object()`>> | Constructs a JSON object from pairs of key and value arguments
+| <<hql-json-array-function,`json_array()`>> | Constructs a JSON array from arguments
+| <<hql-json-value-function,`json_value()`>> | Extracts a value from a JSON document by JSON path
+| <<hql-json-exists-function,`json_exists()`>> | Checks if a JSON path exists in a JSON document
+| <<hql-json-query-function,`json_query()`>> | Queries non-scalar values by JSON path in a JSON document
+| <<hql-json-arrayagg-function,`json_arrayagg()`>> | Creates a JSON array by aggregating values
+| <<hql-json-objectagg-function,`json_objectagg()`>> | Creates a JSON object by aggregating values
+| <<hql-json-set-function,`json_set()`>> | Inserts/Replaces a value by JSON path within a JSON document
+| <<hql-json-remove-function,`json_remove()`>> | Removes a value by JSON path within a JSON document
+| <<hql-json-mergepatch-function,`json_mergepatch()`>> | Merges JSON documents by performing an https://tools.ietf.org/html/rfc7396[RFC 7396] compliant merge
+| <<hql-json-array-append-function,`json_array_append()`>> | Appends to a JSON array of a JSON document by JSON path
+| <<hql-json-array-insert-function,`json_array_insert()`>> | Inserts a value by JSON path to a JSON array within a JSON document
+| <<hql-json-table-function,`json_table()`>> | Turns a JSON document into rows
 |===
 
 
@@ -2203,6 +2204,47 @@ include::{json-example-dir-hql}/JsonArrayInsertTest.java[tags=hql-json-array-ins
 
 WARNING: SAP HANA, DB2, H2 and HSQLDB do not support this function.
 
+[[hql-json-table-function]]
+===== `json_table()`
+
+A <<hql-from-set-returning-functions,set-returning function>>, which turns a JSON document argument into rows.
+Returns no rows if the document is `null` or an empty JSON array.
+
+[[hql-json-table-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/json_table_bnf.txt[]
+----
+
+The first argument is the JSON document. The second optional argument represents the JSON path expression to use
+in order to obtain JSON nodes for further processing. The default for the optional second argument is `$[*]`
+i.e. access of root array elements.
+
+NOTE: If the root of the JSON document is an object, it is recommended to pass `$` as JSON path for portability.
+
+The `passing` clause can be used to pass values for variables in the JSON path.
+
+Attributes/columns that ought to be accessible via the `from` node alias are defined in the `columns` clause,
+which can be of varying forms:
+
+* Value attributes - denoted by a `castTarget` after the name, behaves like <<hql-json-value-function,`json_value()`>>
+* Query attributes - denoted by the `json` type after the name, behaves like <<hql-json-query-function,`json_query()`>>
+* Exists attributes - denoted by the `exists` keyword after the name, behaves like <<hql-json-exists-function,`json_exists()`>>
+* Ordinal attributes - denoted by the `for ordinality` syntax after the name, gives access to the 1-based index of the currently processed array element
+* Nested paths - declare a JSON path for processing of a nested `columns` clause
+
+[[hql-json-table-simple-example]]
+====
+[source, java, indent=0]
+----
+include::{json-example-dir-hql}/JsonTableTest.java[tags=hql-json-table-example]
+----
+====
+
+The `lateral` keyword is mandatory if one of the arguments refer to a from node item of the same query level.
+
+WARNING: H2 support is limited and HSQLDB as well as Sybase ASE do not support this function.
+
 [[hql-functions-xml]]
 ==== Functions for dealing with XML
 
@@ -2959,6 +3001,7 @@ The following set-returning functions are available on many platforms:
 
 | <<hql-array-unnest,`unnest()`>> | Turns an array into rows
 | <<hql-from-set-returning-functions-generate-series,`generate_series()`>> | Creates a series of values as rows
+| <<hql-json-table,`json_table()`>> | Turns a JSON document into rows
 |===
 
 To use set returning functions defined in the database, it is required to register them in a `FunctionContributor`:

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

@@ -0,0 +1,32 @@
+"json_table(" expression ("," expression)? passingClause? columnsClause errorClause? ")"
+
+passingClause
+	: "passing" expression "as" identifier ("," expression "as" identifier)*
+
+columnsClause
+    : "columns(" column ("," column)* ")"
+
+column
+    : "nested" "path"? STRING_LITERAL columnsClause
+    | attributeName "json" wrapperClause? ("path" STRING_LITERAL)? queryOnErrorClause? queryOnEmptyClause?
+    | attributeName "for ordinality"
+    | attributeName "exists" ("path" STRING_LITERAL)? existsOnErrorClause?
+    | attributeName castTarget ("path" STRING_LITERAL)? valueOnErrorClause? valueOnEmptyClause?
+
+queryOnErrorClause
+	: ( "error" | "null" | ( "empty" ( "array" | "object" )? ) ) "on error";
+
+queryOnEmptyClause
+	: ( "error" | "null" | ( "empty" ( "array" | "object" )? ) ) "on empty";
+
+existsOnErrorClause
+	: ( "error" | "true" | "false" ) "on error"
+
+valueOnErrorClause
+	: ( "error" | "null" | ( "default" expression ) ) "on error";
+
+valueOnEmptyClause
+	: ( "error" | "null" | ( "default" expression ) ) "on empty";
+
+errorClause
+	: ( "error" | "null" ) "on error"

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

@@ -519,6 +519,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		functionFactory.unnest_postgresql();
 		functionFactory.generateSeries( null, "ordinality", true );
+		functionFactory.jsonTable_cockroachdb();
 
 		// Postgres uses # instead of ^ for XOR
 		functionContributions.getFunctionRegistry().patternDescriptorBuilder( "bitxor", "(?1#?2)" )

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

@@ -432,13 +432,14 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.listagg( null );
 
 			if ( getDB2Version().isSameOrAfter( 11 ) ) {
-				functionFactory.jsonValue_no_passing();
+				functionFactory.jsonValue_db2();
 				functionFactory.jsonQuery_no_passing();
 				functionFactory.jsonExists_no_passing();
 				functionFactory.jsonObject_db2();
 				functionFactory.jsonArray_db2();
 				functionFactory.jsonArrayAgg_db2();
 				functionFactory.jsonObjectAgg_db2();
+				functionFactory.jsonTable_db2();
 			}
 		}
 

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

@@ -429,6 +429,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		functionFactory.unnest_h2( getMaximumArraySize() );
 		functionFactory.generateSeries_h2( getMaximumSeriesSize() );
+		functionFactory.jsonTable_h2( getMaximumArraySize() );
 	}
 
 	/**

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

@@ -495,7 +495,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonExists_hana();
 
 			functionFactory.unnest_hana();
-//			functionFactory.json_table();
+			functionFactory.jsonTable_hana();
 
 			functionFactory.generateSeries_hana( getMaximumSeriesSize() );
 

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

@@ -100,6 +100,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			if ( getVersion().isSameOrAfter( 10, 3, 3 ) ) {
 				if ( getVersion().isSameOrAfter( 10, 6 ) ) {
 					commonFunctionFactory.unnest_emulated();
+					commonFunctionFactory.jsonTable_mysql();
 				}
 
 				commonFunctionFactory.inverseDistributionOrderedSetAggregates_windowEmulation();

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

@@ -674,6 +674,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 			if ( getMySQLVersion().isSameOrAfter( 8 ) ) {
 				functionFactory.unnest_emulated();
+				functionFactory.jsonTable_mysql();
 			}
 			if ( supportsRecursiveCTE() ) {
 				functionFactory.generateSeries_recursive( getMaximumSeriesSize(), false, false );

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

@@ -312,7 +312,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonValue_oracle();
 			functionFactory.jsonQuery_oracle();
 			functionFactory.jsonExists_oracle();
-			functionFactory.jsonObject_oracle();
+			functionFactory.jsonObject_oracle( getVersion().isSameOrAfter( 19 ) );
 			functionFactory.jsonArray_oracle();
 			functionFactory.jsonArrayAgg_oracle();
 			functionFactory.jsonObjectAgg_oracle();
@@ -323,6 +323,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonMergepatch_oracle();
 			functionFactory.jsonArrayAppend_oracle();
 			functionFactory.jsonArrayInsert_oracle();
+			functionFactory.jsonTable_oracle();
 		}
 
 		functionFactory.xmlelement();

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

@@ -639,6 +639,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.jsonArray();
 			functionFactory.jsonArrayAgg_postgresql( true );
 			functionFactory.jsonObjectAgg_postgresql( true );
+			functionFactory.jsonTable();
 		}
 		else {
 			functionFactory.jsonValue_postgresql();
@@ -656,6 +657,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.jsonArrayAgg_postgresql( false );
 				functionFactory.jsonObjectAgg_postgresql( false );
 			}
+			functionFactory.jsonTable_postgresql();
 		}
 		functionFactory.jsonSet_postgresql();
 		functionFactory.jsonRemove_postgresql();