examples for native functions

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

@@ -1056,14 +1056,33 @@ Finally, functions that evaluate the id, version, or natural id of an entity:
 [[hql-user-defined-functions]]
 ==== Native and user-defined functions
 
+The functions we've described above are the functions abstracted by HQL and made portable across databases.
+But, of course, HQL can't abstract every function in your database.
+
 There are several ways to call native or user-defined SQL functions.
 
 - A native or user-defined function may be called using JPQL's `function` syntax, for example, ``function('sinh', phi)``.
+  (This is the easiest way, but not the best way.)
 - A user-written `FunctionContributor` may register user-defined functions.
-- A custom `Dialect` may register additional native functions be overriding `initializeFunctionRegistry()`.
+- A custom `Dialect` may register additional native functions by overriding `initializeFunctionRegistry()`.
 
+[TIP]
+====
 Registering a function isn't hard, but is beyond the scope of this chapter.
 
+(It's even possible to use the APIs Hibernate provides to make your own _portable_ functions!)
+====
+
+Fortunately, every built-in `Dialect` already registers many native functions for the database it supports.
+
+[[hql-var-function-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-native-function-example]
+----
+====
+
 [[hql-conditional-expressions]]
 === Predicates
 

documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java

@@ -1660,24 +1660,38 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 	}
 
 	@Test
-	@RequiresDialect(H2Dialect.class)
-	@RequiresDialect(OracleDialect.class)
-	@RequiresDialect(MySQLDialect.class)
+	@RequiresDialect({MySQLDialect.class, PostgreSQLDialect.class, H2Dialect.class, DerbyDialect.class, OracleDialect.class})
+	public void test_var_function_example() {
+		doInJPA(this::entityManagerFactory, entityManager -> {
+			//tag::hql-native-function-example[]
+			// careful: these functions are not supported on all databases!
+
+			List<Tuple> variances = entityManager.createQuery(
+				"select var_samp(c.duration) as sampvar, var_pop(c.duration) as popvar " +
+				"from Call c ",
+				Tuple.class)
+			.getResultList();
+			//end::hql-native-function-example[]
+		});
+	}
+
+	@Test
+	@RequiresDialect({H2Dialect.class, MySQLDialect.class, PostgreSQLDialect.class, OracleDialect.class})
 	public void test_hql_bit_length_function_example() {
 		doInJPA(this::entityManagerFactory, entityManager -> {
-			//tag::hql-bit-length-function-example[]
+			//tag::hql-native-function-example[]
+
 			List<Number> bits = entityManager.createQuery(
-				"select bit_length(c.duration) " +
+				"select bit_length(c.phone.number) " +
 				"from Call c ",
 				Number.class)
 			.getResultList();
-			//end::hql-bit-length-function-example[]
+			//end::hql-native-function-example[]
 			assertEquals(2, bits.size());
 		});
 	}
 
 	@Test
-	@SkipForDialect(value = DerbyDialect.class, comment = "See https://issues.apache.org/jira/browse/DERBY-2072")
 	public void test_hql_cast_function_example() {
 		doInJPA(this::entityManagerFactory, entityManager -> {
 			//tag::hql-cast-function-example[]
@@ -1692,7 +1706,6 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 	}
 
 	@Test
-	@SkipForDialect(value = DerbyDialect.class, comment = "Derby doesn't support extract function")
 	public void test_hql_extract_function_example() {
 		doInJPA(this::entityManagerFactory, entityManager -> {
 			//tag::hql-extract-function-example[]