HHH-18731 Add generate_series() set-returning function

Author: beikov

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

@@ -2958,7 +2958,7 @@ The following set-returning functions are available on many platforms:
 | Function | purpose
 
 | <<hql-array-unnest,`unnest()`>> | Turns an array into rows
-//| `generate_series()` | Creates a series of values as rows
+| <<hql-from-set-returning-functions-generate-series,`generate_series()`>> | Creates a series of values as rows
 |===
 
 To use set returning functions defined in the database, it is required to register them in a `FunctionContributor`:
@@ -2986,6 +2986,43 @@ which is not supported on some databases for user defined functions.
 Hibernate ORM tries to emulate this feature by wrapping invocations as lateral subqueries and using `row_number()`,
 which may lead to worse performance.
 
+[[hql-from-set-returning-functions-generate-series]]
+==== `generate_series` set-returning function
+
+A <<hql-from-set-returning-functions,set-returning function>>, which generates rows from a given start value (inclusive)
+up to a given stop value (inclusive). The function has 2 variants:
+
+* `generate_series(numeric, numeric [,numeric])` - Arguments are `start`, `stop` and `step` with a default of `1` for the optional `step` argument
+* `generate_series(temporal, temporal, duration)` - Like the numeric variant, but for temporal types and `step` is required
+
+[[hql-generate-series-example]]
+====
+[source, java, indent=0]
+----
+include::{srf-example-dir-hql}/GenerateSeriesTest.java[tags=hql-set-returning-function-generate-series-example]
+----
+====
+
+To obtain the "row number" of a generated value i.e. ordinality, it is possible to use the `index()` function.
+
+[[hql-generate-series-ordinality-example]]
+====
+[source, java, indent=0]
+----
+include::{srf-example-dir-hql}/GenerateSeriesTest.java[tags=hql-set-returning-function-generate-series-ordinality-example]
+----
+====
+
+The `step` argument can be a negative value and progress from a higher `start` value to a lower `stop` value.
+
+[[hql-generate-series-temporal-example]]
+====
+[source, java, indent=0]
+----
+include::{srf-example-dir-hql}/GenerateSeriesTest.java[tags=hql-set-returning-function-generate-series-temporal-example]
+----
+====
+
 [[hql-join]]
 === Declaring joined entities
 

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

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

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

@@ -458,6 +458,18 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.xmlagg();
 
 		functionFactory.unnest_emulated();
+		if ( supportsRecursiveCTE() ) {
+			functionFactory.generateSeries_recursive( getMaximumSeriesSize(), false, true );
+		}
+	}
+
+	/**
+	 * DB2 doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with a top level recursive CTE which requires an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		return 10000;
 	}
 
 	@Override

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() );
 	}
 
 	/**
@@ -441,6 +442,16 @@ protected int getMaximumArraySize() {
 		return 1000;
 	}
 
+	/**
+	 * Since H2 doesn't support ordinality for the {@code system_range} function or {@code lateral},
+	 * it's impossible to use {@code system_range} for non-constant cases.
+	 * Luckily, correlation can be emulated, but requires that there is an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		return 10000;
+	}
+
 	@Override
 	public @Nullable String getDefaultOrdinalityColumnName() {
 		return "nord";

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

@@ -497,6 +497,8 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.unnest_hana();
 //			functionFactory.json_table();
 
+			functionFactory.generateSeries_hana( getMaximumSeriesSize() );
+
 			if ( getVersion().isSameOrAfter(2, 0, 20 ) ) {
 				if ( getVersion().isSameOrAfter( 2, 0, 40 ) ) {
 					// Introduced in 2.0 SPS 04
@@ -513,6 +515,14 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 	}
 
+	/**
+	 * HANA doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with the {@code xmltable} and {@code lpad} functions.
+	 */
+	protected int getMaximumSeriesSize() {
+		return 10000;
+	}
+
 	@Override
 	public SqlAstTranslatorFactory getSqlAstTranslatorFactory() {
 		return new StandardSqlAstTranslatorFactory() {

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

@@ -279,6 +279,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		}
 
 		functionFactory.unnest( "c1", "c2" );
+		functionFactory.generateSeries_recursive( getMaximumSeriesSize(), true, false );
 
 		//trim() requires parameters to be cast when used as trim character
 		functionContributions.getFunctionRegistry().register( "trim", new TrimFunction(
@@ -288,6 +289,16 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		) );
 	}
 
+	/**
+	 * HSQLDB doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with a top level recursive CTE which requires an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		// The maximum recursion depth of HSQLDB
+		return 258;
+	}
+
 	@Override
 	public @Nullable String getDefaultOrdinalityColumnName() {
 		return "c2";

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

@@ -676,9 +676,22 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			if ( getMySQLVersion().isSameOrAfter( 8 ) ) {
 				functionFactory.unnest_emulated();
 			}
+			if ( supportsRecursiveCTE() ) {
+				functionFactory.generateSeries_recursive( getMaximumSeriesSize(), false, false );
+			}
 		}
 	}
 
+	/**
+	 * MySQL doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with a top level recursive CTE which requires an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		// The maximum recursion depth of MySQL
+		return 1000;
+	}
+
 	@Override
 	public void contributeTypes(TypeContributions typeContributions, ServiceRegistry serviceRegistry) {
 		super.contributeTypes( typeContributions, serviceRegistry );

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

@@ -335,6 +335,16 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.xmlagg();
 
 		functionFactory.unnest_oracle();
+		functionFactory.generateSeries_recursive( getMaximumSeriesSize(), true, false );
+	}
+
+	/**
+	 * Oracle doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with a top level recursive CTE which requires an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		return 10000;
 	}
 
 	@Override

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

@@ -711,6 +711,7 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		else {
 			functionFactory.unnest_postgresql();
 		}
+		functionFactory.generateSeries( null, "ordinality", false );
 	}
 
 	@Override

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

@@ -440,13 +440,32 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 			functionFactory.leastGreatest();
 			functionFactory.dateTrunc_datetrunc();
 			functionFactory.trunc_round_datetrunc();
+			functionFactory.generateSeries_sqlserver( getMaximumSeriesSize() );
 		}
 		else {
 			functionContributions.getFunctionRegistry().register(
 					"trunc",
 					new SqlServerConvertTruncFunction( functionContributions.getTypeConfiguration() )
 			);
 			functionContributions.getFunctionRegistry().registerAlternateKey( "truncate", "trunc" );
+			if ( supportsRecursiveCTE() ) {
+				functionFactory.generateSeries_recursive( getMaximumSeriesSize(), false, false );
+			}
+		}
+	}
+
+	/**
+	 * SQL Server doesn't support the {@code generate_series} function or {@code lateral} recursive CTEs,
+	 * so it has to be emulated with a top level recursive CTE which requires an upper bound on the amount
+	 * of elements that the series can return.
+	 */
+	protected int getMaximumSeriesSize() {
+		if ( getVersion().isSameOrAfter( 16 ) ) {
+			return 10000;
+		}
+		else {
+			// The maximum recursion depth of SQL Server
+			return 100;
 		}
 	}