From 2d66576b920a23ef4d42c2219ddbd0252ca236bc Mon Sep 17 00:00:00 2001
From: Steve Ebersole <steve@hibernate.org>
Date: Thu, 7 Jul 2005 03:35:22 +0000
Subject: [PATCH] completed insert select support

git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@7396 1b8cb986-b30d-0410-93ca-fae66ebed9b2
---
 reference/en/modules/batch.xml | 43 +++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/reference/en/modules/batch.xml b/reference/en/modules/batch.xml
index ef26155bcc..197cb6ae89 100755
--- a/reference/en/modules/batch.xml
+++ b/reference/en/modules/batch.xml
@@ -95,7 +95,7 @@ session.close();]]></programlisting>
 
     </sect1>
 
-    <sect1 id="batch-direct" revision="1">
+    <sect1 id="batch-direct" revision="2">
         <title>DML-style operations</title>
 
         <para>
@@ -188,7 +188,7 @@ session.close();]]></programlisting>
 
         <para>
             The psuedo-syntax for <literal>INSERT</literal> statements is:
-            <literal>INSERT INTO EntityName (properties_list)? select_statement</literal>.  Some
+            <literal>INSERT INTO EntityName properties_list select_statement</literal>.  Some
             points to note:
         </para>
 
@@ -198,18 +198,15 @@ session.close();]]></programlisting>
                     Only the INSERT INTO ... SELECT ... form is supported; not the INSERT INTO ... VALUES ... form.
                 </para>
                 <para>
-                    The properties_list is optional.  It is analogous to the <literal>column speficiation</literal>
-                    in the SQL <literal>INSERT</literal> statement.  If omitted, all "eligible" (see next) properties are
-                    automatically included.
+                    The properties_list is analogous to the <literal>column speficiation</literal>
+                    in the SQL <literal>INSERT</literal> statement.  For entities involved in mapped
+                    inheritence, only properties directly defined on that given class-level can be
+                    used in the properties_list.  Superclass properties are not allowed; and subclass
+                    properties do not make sense.  In other words, <literal>INSERT</literal>
+                    statements are inherently non-polymorphic.
                 </para>
             </listitem>
             <listitem>
-                <para>
-                    For entities involved in mapped inheritence, only properties directly defined on that
-                    given class-level can be used in the properties_list.  Superclass properties are not
-                    allowed; and subclass properties do not make sense.  In other words, <literal>INSERT</literal>
-                    statements are inherently non-polymorphic.
-                </para>
                 <para>
                     select_statement can be any valid HQL select query, with the caveat that the return types
                     must match the types expected by the insert.  Currently, this is checked during query
@@ -221,6 +218,30 @@ session.close();]]></programlisting>
                     database might not make a distinction or might be able to handle the conversion.
                 </para>
             </listitem>
+            <listitem>
+                <para>
+                    For the id property, the insert statement gives you two options.  You can either
+                    explicitly specify the id property in the properties_list (in which case its value
+                    is taken from the corresponding select expression) or omit it from the properties_list
+                    (in which case a generated value is used).  This later option is only available when
+                    using id generators that operate in the database; attempting to use this option with
+                    any "in memory" type generators will cause an exception during parsing.  Note that
+                    for the purposes of this discussion, in-database generators are considered to be
+                    <literal>org.hibernate.id.SequenceGenerator</literal> (and its subclasses) and
+                    any implementors of <literal>org.hibernate.id.PostInsertIdentifierGenerator</literal>.
+                    The most notable exception here is <literal>org.hibernate.id.TableHiLoGenerator</literal>,
+                    which cannot be used because it does not expose a selectable way to get its values.
+                </para>
+            </listitem>
+            <listitem>
+                <para>
+                    For properties mapped as either <literal>version</literal> or <literal>timestamp</literal>,
+                    the insert statement gives you two options.  You can either specify the property in the
+                    properties_list (in which case its value is taken from the corresponding select expressions)
+                    or omit it from the properties_list (in which case the <literal>seed value</literal> defined
+                    by the <literal>org.hibernate.type.VersionType</literal> is used).
+                </para>
+            </listitem>
         </itemizedlist>
 
         <para>