NH-3488 - reference documentation for this new feature. To be squashed.

Author: fredericDelaporte

doc/reference/modules/query_linq.xml

@@ -467,6 +467,84 @@ IList<Cat> oldCats =
         .ToList();]]></programlisting>
   </sect1>
 
+  <sect1 id="querylinq-modifying">
+    <title>Modifying entities inside the database</title>
+
+    <para>
+      Beginning with NHibernate 5, Linq queries can be used for inserting, updating or deleting entities.
+      The query defines the data to delete, update or insert, and then <literal>Delete</literal>,
+      <literal>Update</literal> and <literal>Insert</literal> queryable extension methods allow
+      to delete it, or instruct in which way it should updated or inserted. Those queries then happen
+      entirely inside the database, without extracting corresponding entities out of the database.
+    </para>
+
+    <sect2 id="querylinq-modifying-insert">
+      <title>Inserting new entities</title>
+      <para>
+        <literal>Insert</literal> method extension expects a queryable defining the data source of the insert.
+        This data can be entities or a projection. Then it allows specifying the target entity type to insert,
+        and how to convert source data to those target entities. Two forms of target specification exist.
+      </para>
+      <para>
+        Using projection to target entity:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Insert()
+    .As(c => new Dog { Name = c.Name + "dog", BodyWeight = c.BodyWeight });]]></programlisting>
+      <para>
+        Or using assignments:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Insert()
+    .Into<Dog>(a => a
+        .Set(d => d.Name, c => c.Name + "dog")
+        .Set(d => d.BodyWeight, c => c.BodyWeight));]]></programlisting>
+      <para>
+        In both cases, unspecified properties are not included in the resulting SQL insert.
+      </para>
+    </sect2>
+
+    <sect2 id="querylinq-modifying-update">
+      <title>Updating entities</title>
+      <para>
+        <literal>Update</literal> method extension expects a queryable defining the entities to update.
+        Then it allows specifying which properties should be updated with which values. As for
+        <literal>Insert</literal>, two forms of target specification exist.
+      </para>
+      <para>
+        Using projection to updated entity:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Update()
+    .As(c => new Cat { BodyWeight = c.BodyWeight / 2 });]]></programlisting>
+      <para>
+        Or using assignments:
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Update()
+    .Assign(a => a
+        .Set(c => c.BodyWeight, c => c.BodyWeight / 2));]]></programlisting>
+      <para>
+        In both cases, unspecified properties are not included in the resulting SQL update.
+      </para>
+    </sect2>
+
+    <sect2 id="querylinq-modifying-delete">
+      <title>Deleting entities</title>
+      <para>
+        <literal>Delete</literal> method extension expects a queryable defining the entities to delete.
+        It immediately deletes them.
+      </para>
+      <programlisting><![CDATA[session.Query<Cat>()
+    .Where(c => c.BodyWeight > 20)
+    .Delete();]]></programlisting>
+    </sect2>
+  </sect1>
+
   <sect1 id="querylinq-querycache">
     <title>Query cache</title>