From 7ea607a7c849610a6314fbbcab3e77c66dbb2e26 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Sat, 7 Sep 2024 16:44:25 +0200
Subject: [PATCH] HHH-18584 add to migration guide

Signed-off-by: Gavin King <gavin@hibernate.org>
---
 migration-guide.adoc | 48 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/migration-guide.adoc b/migration-guide.adoc
index dd2d2da709..e98582cc34 100644
--- a/migration-guide.adoc
+++ b/migration-guide.adoc
@@ -115,8 +115,54 @@ String isDefault();
 ----
 
 
+[[create-query]]
+== Queries with implicit `select` list and no explicit result type
+
+In previous versions, Hibernate allowed a query with no `select` list to be passed to the overload of `createQuery()` with no explicit result type parameter, for example:
+
+[source,java]
+List query =
+        session.createQuery("from X, Y")
+                .getResultList()
+
+or:
+
+[source,java]
+List query =
+        session.createQuery("from X join y")
+                .getResultList()
+
+The select list was inferred based on the `from` clause.
+
+In Hibernate 6 we decided to deprecate this overload of `createQuery()`, since:
+
+- it returns a raw type, resulting in compiler warnings in client code, and
+- the second query is truly ambiguous, with no obviously intuitive interpretation.
+
+As of Hibernate 7, the method is remains deprecated, and potentially-ambiguous queries _are no longer accepted_.
+Migration paths include:
+
+1. explicitly specify the `select` list,
+2. add `X.class` or `Object[].class` as a second argument, to disambiguate the interpretation of the query, or
+3. in the case where the query should return exactly one entity, explicitly assign the alias `this` to that entity.
+
+For example, the queries above may be migrated via:
+
+[source,java]
+List<Object[]> result =
+        session.createQuery("from X, Y", Object[].class)
+                .getResultList()
+
+or:
+
+[source,java]
+List<X> result =
+        session.createQuery("from X join y", X.class)
+                .getResultList()
+
+
 [[proxy-annotation]]
-== Replace @Proxy
+== Replace `@Proxy`
 
 Applications will need to replace usages of the removed `@Proxy` annotation.