HHH-18759 Add xmltable() set-returning function

Author: beikov

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

@@ -2257,14 +2257,15 @@ it is necessary to enable the `hibernate.query.hql.xml_functions_enabled` config
 |===
 | Function | Purpose
 
-| `xmlelement()` | Constructs an XML element from arguments
-| `xmlcomment()` | Constructs an XML comment from the single argument
-| `xmlforest()` | Constructs an XML forest from the arguments
-| `xmlconcat()` | Concatenates multiple XML fragments to each other
-| `xmlpi()` | Constructs an XML processing instruction
-| `xmlquery()` | Extracts content from XML document using XQuery or XPath
-| `xmlexists()` | Checks if an XQuery or XPath expression exists in an XML document
-| `xmlagg()` | Aggregates XML elements by concatenation
+| <<hql-xmlelement-function,`xmlelement()`>> | Constructs an XML element from arguments
+| <<hql-xmlcomment-function,`xmlcomment()`>> | Constructs an XML comment from the single argument
+| <<hql-xmlforest-function,`xmlforest()`>> | Constructs an XML forest from the arguments
+| <<hql-xmlconcat-function,`xmlconcat()`>> | Concatenates multiple XML fragments to each other
+| <<hql-xmlpi-function,`xmlpi()`>> | Constructs an XML processing instruction
+| <<hql-xmlquery-function,`xmlquery()`>> | Extracts content from XML document using XQuery or XPath
+| <<hql-xmlexists-function,`xmlexists()`>> | Checks if an XQuery or XPath expression exists in an XML document
+| <<hql-xmlagg-function,`xmlagg()`>> | Aggregates XML elements by concatenation
+| <<hql-xmltable-function,`xmltable()`>> | Turns an XML document into rows
 |===
 
 
@@ -2461,6 +2462,39 @@ include::{xml-example-dir-hql}/XmlAggTest.java[tags=hql-xmlagg-example]
 
 WARNING: SAP HANA, MySQL, MariaDB and HSQLDB do not support this function.
 
+[[hql-xmltable-function]]
+===== `xmltable()`
+
+A <<hql-from-set-returning-functions,set-returning function>>, which turns an XML document argument into rows.
+Returns no rows if the document is `null` or the XPath expression resolves to no nodes.
+
+[[hql-xmltable-bnf]]
+[source, antlrv4, indent=0]
+----
+include::{extrasdir}/xmltable_bnf.txt[]
+----
+
+The first argument is the XPath expression. The second argument represents the XML document expression.
+
+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, will cast the content of the XML node matching the XPath expression of the column
+* Query attributes - denoted by the `xml` type after the name, returns the XML node matching the XPath expression of the column
+* Ordinal attributes - denoted by the `for ordinality` syntax after the name, gives access to the 1-based index of the currently processed XML node
+
+[[hql-xmltable-simple-example]]
+====
+[source, java, indent=0]
+----
+include::{xml-example-dir-hql}/XmlTableTest.java[tags=hql-xml-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, MySQL, MariaDB and HSQLDB do not support this function.
+
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 
@@ -3001,7 +3035,8 @@ 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
+| <<hql-json-table-function,`json_table()`>> | Turns a JSON document into rows
+| <<hql-xmltable-function,`xmltable()`>> | Turns an XML 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/xmltable_bnf.txt

@@ -0,0 +1,12 @@
+"xmltable(" expression "passing" expression columnsClause ")"
+
+columnsClause
+    : "columns" column ("," column)*
+
+column
+    : attributeName "xml" ("path" STRING_LITERAL)? defaultClause?
+    | attributeName "for ordinality"
+    | attributeName castTarget ("path" STRING_LITERAL)? defaultClause?
+
+defaultClause
+	: "default" expression;

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

@@ -457,6 +457,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.xmlexists_db2_legacy();
 		}
 		functionFactory.xmlagg();
+		functionFactory.xmltable_db2();
 
 		functionFactory.unnest_emulated();
 		if ( supportsRecursiveCTE() ) {

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

@@ -508,7 +508,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 					functionFactory.jsonObjectAgg_hana();
 				}
 
-//				functionFactory.xmltable();
+				functionFactory.xmltable_hana();
 			}
 
 //			functionFactory.xmlextract();

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

@@ -334,6 +334,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.xmlquery_oracle();
 		functionFactory.xmlexists();
 		functionFactory.xmlagg();
+		functionFactory.xmltable_oracle();
 
 		functionFactory.unnest_oracle();
 		functionFactory.generateSeries_recursive( getMaximumSeriesSize(), true, false );

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

@@ -678,6 +678,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.xmlquery_postgresql();
 		functionFactory.xmlexists();
 		functionFactory.xmlagg();
+		functionFactory.xmltable( true );
 
 		if ( getVersion().isSameOrAfter( 9, 4 ) ) {
 			functionFactory.makeDateTimeTimestamp();

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

@@ -429,6 +429,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.xmlquery_sqlserver();
 		functionFactory.xmlexists_sqlserver();
 		functionFactory.xmlagg_sqlserver();
+		functionFactory.xmltable_sqlserver();
 
 		functionFactory.unnest_sqlserver();
 

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

@@ -167,6 +167,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 
 		functionFactory.unnest_sybasease();
 		functionFactory.generateSeries_sybasease( getMaximumSeriesSize() );
+		functionFactory.xmltable_sybasease();
 	}
 
 	/**

hibernate-core/src/main/antlr/org/hibernate/grammars/hql/HqlLexer.g4

@@ -336,13 +336,15 @@ WITH				: [wW] [iI] [tT] [hH];
 WITHIN				: [wW] [iI] [tT] [hH] [iI] [nN];
 WITHOUT				: [wW] [iI] [tT] [hH] [oO] [uU] [tT];
 WRAPPER				: [wW] [rR] [aA] [pP] [pP] [eE] [rR];
+XML 				: [xX] [mM] [lL];
 XMLAGG				: [xX] [mM] [lL] [aA] [gG] [gG];
 XMLATTRIBUTES		: [xX] [mM] [lL] [aA] [tT] [tT] [rR] [iI] [bB] [uU] [tT] [eE] [sS];
 XMLELEMENT			: [xX] [mM] [lL] [eE] [lL] [eE] [mM] [eE] [nN] [tT];
 XMLEXISTS			: [xX] [mM] [lL] [eE] [xX] [iI] [sS] [tT] [sS];
 XMLFOREST			: [xX] [mM] [lL] [fF] [oO] [rR] [eE] [sS] [tT];
 XMLPI				: [xX] [mM] [lL] [pP] [iI];
 XMLQUERY			: [xX] [mM] [lL] [qQ] [uU] [eE] [rR] [yY];
+XMLTABLE			: [xX] [mM] [lL] [tT] [aA] [bB] [lL] [eE];
 YEAR				: [yY] [eE] [aA] [rR];
 ZONED				: [zZ] [oO] [nN] [eE] [dD];
 

hibernate-core/src/main/antlr/org/hibernate/grammars/hql/HqlParser.g4

@@ -1119,6 +1119,7 @@ function
 setReturningFunction
 	: simpleSetReturningFunction
 	| jsonTableFunction
+	| xmltableFunction
 	;
 
 /**
@@ -1813,6 +1814,24 @@ xmlaggFunction
 	: XMLAGG LEFT_PAREN expression orderByClause? RIGHT_PAREN filterClause? overClause?
 	;
 
+xmltableFunction
+	: XMLTABLE LEFT_PAREN expression PASSING expression xmltableColumnsClause RIGHT_PAREN
+	;
+
+xmltableColumnsClause
+    : COLUMNS xmltableColumn (COMMA xmltableColumn)*
+    ;
+
+xmltableColumn
+    : identifier XML (PATH STRING_LITERAL)? xmltableDefaultClause?          # XmlTableQueryColumn
+    | identifier FOR ORDINALITY                                             # XmlTableOrdinalityColumn
+    | identifier castTarget (PATH STRING_LITERAL)? xmltableDefaultClause?   # XmlTableValueColumn
+    ;
+
+xmltableDefaultClause
+    : DEFAULT expression
+    ;
+
 /**
  * Support for "soft" keywords which may be used as identifiers
  *
@@ -2025,13 +2044,15 @@ xmlaggFunction
 	| WITHIN
 	| WITHOUT
 	| WRAPPER
+	| XML
 	| XMLAGG
 	| XMLATTRIBUTES
 	| XMLELEMENT
 	| XMLEXISTS
 	| XMLFOREST
 	| XMLPI
 	| XMLQUERY
+	| XMLTABLE
 	| YEAR
 	| ZONED) {
 		logUseOfReservedWordAsIdentifier( getCurrentToken() );