[#26284] Update ORM and Reactive Panache guides

Add example for Panache .project with HQL query with a select clause

docs/src/main/asciidoc/hibernate-orm-panache.adoc

@@ -772,6 +772,7 @@ If in the DTO projection object you have a field from a referenced entity, you c
 public class Dog extends PanacheEntity {
     public String name;
     public String race;
+    public Double weight;
     @ManyToOne
     public Person owner;
 }
@@ -791,6 +792,45 @@ PanacheQuery<DogDto> query = Dog.findAll().project(DogDto.class);
 ----
 <1> The `ownerName` DTO constructor's parameter will be loaded from the `owner.name` HQL property.
 
+It's also possible to specify a HQL query with a select clause. In this case, the projection class must have a constructor
+matching the values returned by the select clause:
+
+[source,java]
+----
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+@RegisterForReflection 
+public class RaceWeight {
+    public final String race;
+    public final Double weight;
+
+    public RaceWeight(String race) {
+        this(race, null);
+    }
+
+    public RaceWeight(String race, Double weight) { // <1>
+        this.race = race;
+        this.weight = weight;
+    }
+}
+
+// Only the race and the average weight will be loaded
+PanacheQuery<RaceWeight> query = Person.find("select d.race, AVG(d.weight) from Dog d group by d.race).project(RaceWeight.class);
+----
+<1> Hibernate ORM will use this constructor. When the query has a select clause, it's possible to have multiple constructors.
+
+[WARNING]
+====
+It's not possible to have a HQL `select new` query and `.project(Class)` at the same time - you need to pick one approach.
+
+For example, this will fail:
+
+[source,java]
+----
+PanacheQuery<RaceWeight> query = Person.find("select new MyView(d.race, AVG(d.weight)) from Dog d group by d.race).project(AnotherView.class);
+----
+====
+
 == Multiple Persistence Units
 
 The support for multiple persistence units is described in detail in xref:hibernate-orm.adoc#multiple-persistence-units[the Hibernate ORM guide].

docs/src/main/asciidoc/hibernate-reactive-panache.adoc

@@ -655,6 +655,7 @@ If in the DTO projection object you have a field from a referenced entity, you c
 public class Dog extends PanacheEntity {
     public String name;
     public String race;
+    public Double weight;
     @ManyToOne
     public Person owner;
 }
@@ -674,6 +675,43 @@ PanacheQuery<DogDto> query = Dog.findAll().project(DogDto.class);
 ----
 <1> The `ownerName` DTO constructor's parameter will be loaded from the `owner.name` HQL property.
 
+It's also possible to specify a HQL query with a select clause. In this case, the projection class must have a constructor
+matching the values returned by the select clause:
+
+source,java]
+----
+import io.quarkus.runtime.annotations.RegisterForReflection;
+
+@RegisterForReflection 
+public class RaceWeight {
+    public final String race;
+    public final Double weight
+
+    public RaceWeight(String race) {
+        this(race, null);
+    }
+
+    public RaceWeight(String race, Double weight) { // <1>
+        this.race = race;
+        this.weight = weight;
+    }
+}
+
+// Only the race and the average weight will be loaded
+PanacheQuery<RaceWeight> query = Person.find("select d.race, AVG(d.weight) from Dog d group by d.race).project(RaceWeight.class);
+----
+<1> Hibernate Reactive will use this constructor. When the query has a select clause, it's possible to have multiple constructors.
+
+[WARNING]
+====
+It's not possible to have a HQL `select new` query and `.project(Class)` at the same time - you need to pick one approach.
+
+For example, this will fail:
+```
+PanacheQuery<RaceWeight> query = Person.find("select new MyView(d.race, AVG(d.weight)) from Dog d group by d.race).project(AnotherView.class);
+```
+====
+
 == Multiple Persistence Units
 
 Hibernate Reactive in Quarkus currently does not support multiple persistence units.