From 4cdc1e23f56d7330c97b8a8716e95e232bb81de4 Mon Sep 17 00:00:00 2001
From: Gavin King <gavin@hibernate.org>
Date: Mon, 4 Jul 2005 02:41:38 +0000
Subject: [PATCH] docd aliasesless sql queries

git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@7366 1b8cb986-b30d-0410-93ca-fae66ebed9b2
---
 reference/en/modules/query_sql.xml | 42 +++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/reference/en/modules/query_sql.xml b/reference/en/modules/query_sql.xml
index 48afabf680..87a3bd99ff 100644
--- a/reference/en/modules/query_sql.xml
+++ b/reference/en/modules/query_sql.xml
@@ -13,17 +13,45 @@
         all create, update, delete, and load operations. 
     </para>
 
-    <sect1 id="querysql-creating">
-        <title>Creating a native SQL <literal>Query</literal></title>
+    <sect1 id="querysql-creating" revision="2">
+        <title>Using a <literal>SQLQuery</literal></title>
 
         <para>
-            SQL queries are controlled via the <literal>SQLQuery</literal> interface, which 
-            is obtained by calling <literal>Session.createSQLQuery()</literal>.
+            Execution of native SQL queries is controlled via the <literal>SQLQuery</literal> interface, 
+            which is obtained by calling <literal>Session.createSQLQuery()</literal>. In extremely
+            simple cases, we can use the following form:
+        </para>
+
+        <programlisting><![CDATA[List cats = sess.createSQLQuery("select * from cats")
+    .addEntity(Cat.class)
+    .list();]]></programlisting>
+    
+        <para>
+            This query specified:
+        </para>
+
+        <itemizedlist>
+        <listitem>
+        <para>
+            the SQL query string
+        </para>
+        </listitem>
+        <listitem>
+        <para>
+            the entity returned by the query
+        </para>
+        </listitem>
+        </itemizedlist>
+
+        <para>
+            Here, the result set column names are assumed to be the same as the column names
+            specified in the mapping document. This can be problematic for SQL queries which
+            join multiple tables, since the same column names may appear in more than one
+            table. The following form is not vulnerable to column name duplication:
         </para>
 
         <programlisting><![CDATA[List cats = sess.createSQLQuery("select {cat.*} from cats cat")
     .addEntity("cat", Cat.class)
-    .setMaxResults(50)
     .list();]]></programlisting>
 
         <para>
@@ -44,8 +72,8 @@
         </itemizedlist>
     
         <para>
-            The <literal>addEntity()</literal> method associates SQL table aliases with entity classes,
-            and determines the shape of the query result set.
+            The <literal>addEntity()</literal> method associates the SQL table alias with the returned 
+            entity class, and determines the shape of the query result set.
         </para>
         
         <para>