From bb29e3b060109e5965b8a62a513c859f5fc09cfa Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Fri, 24 Jun 2022 15:48:41 +0200
Subject: [PATCH] document root joins

---
 .../chapters/query/hql/QueryLanguage.adoc     | 25 ++++++++++++++++---
 .../org/hibernate/userguide/hql/HQLTest.java  | 17 +++++++++++++
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
index 326e9ad2cc..024d1ed80e 100644
--- a/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
+++ b/documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc
@@ -1494,8 +1494,27 @@ There are:
 - _explicit joins_, declared within the `from` clause using the keyword ``join``,
 - and _implicit joins_, which don't need to be declared in the `from` clause.
 
+[[hql-root-join]]
+==== Explicit root joins
+
+An explicit root join works just like an ANSI-style join in SQL.
+
+[[hql-explicit-root-join-example]]
+//.Explicit root join examples
+====
+[source, SQL, indent=0]
+----
+include::{sourcedir}/HQLTest.java[tags=hql-explicit-root-join-example]
+----
+====
+
+[NOTE]
+====
+This looks nice and familiar, but it's _not_ the most common sort of join in HQL or JPQL.
+====
+
 [[hql-explicit-join]]
-==== Explicit joins
+==== Explicit association joins
 
 An explicit association join is declared using the `join` keyword.
 An explicit join may be either:
@@ -1537,7 +1556,7 @@ include::{sourcedir}/HQLTest.java[tags=hql-explicit-outer-join-example]
 For further information about collection-valued association references, see <<hql-collection-valued-associations>>.
 
 [[hql-explicit-join-conditions]]
-==== Explicit joins with join conditions
+==== Explicit association joins with join conditions
 
 The `with` or `on` clause allows explicit qualification of the join conditions.
 
@@ -1666,7 +1685,7 @@ But emulation is neither very efficient, nor does it support all possible query
 ====
 
 [[hql-implicit-join]]
-==== Implicit joins (path expressions)
+==== Implicit association joins (path expressions)
 
 It's not necessary to explicitly `join` every entity that occurs in a query.
 Instead, entity associations may be _navigated_, just like in Java:
diff --git a/documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java b/documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java
index da7a6ec01f..9fa5efdee2 100644
--- a/documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java
+++ b/documentation/src/test/java/org/hibernate/userguide/hql/HQLTest.java
@@ -308,6 +308,23 @@ public class HQLTest extends BaseEntityManagerFunctionalTestCase {
 		});
 	}
 
+	@Test
+	public void test_hql_explicit_root_join_example_1() {
+		doInJPA(this::entityManagerFactory, entityManager -> {
+			//tag::hql-explicit-root-join-example[]
+			List<Person> persons = entityManager.createQuery(
+				"select distinct pr " +
+				"from Person pr " +
+				"join Phone ph on ph.person = pr " +
+				"where ph.type = :phoneType",
+				Person.class)
+			.setParameter("phoneType", PhoneType.MOBILE)
+			.getResultList();
+			//end::hql-explicit-root-join-example[]
+			assertEquals(1, persons.size());
+		});
+	}
+
 	@Test
 	public void test_hql_explicit_inner_join_example_1() {
 		doInJPA(this::entityManagerFactory, entityManager -> {