From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 16 Jan 2010 21:31:07 +0000 (+0000)
Subject: add a doc for query.delete()
X-Git-Tag: rel_0_6beta1~69
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=00df05061e7a0333022d02705c21270f9de4edab;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add a doc for query.delete()
---

diff --git a/doc/build/session.rst b/doc/build/session.rst
index da858a2ef4..cbd33357b2 100644
--- a/doc/build/session.rst
+++ b/doc/build/session.rst
@@ -249,6 +249,17 @@ The solution is to use proper cascading::
     del user.addresses[1]
     session.flush()
 
+Deleting based on Filter Criterion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The caveat with ``Session.delete()`` is that you need to have an object handy already in order to delete.   The Query includes a ``delete()`` method which deletes based on filtering criteria::
+
+    session.query(User).filter(User.id==7).delete()
+    
+The ``Query.delete()`` method includes functionality to "expire" objects already in the session which 
+match the criteria.   However it does have some caveats, including that "delete" and "delete-orphan" 
+cascades won't be fully expressed for collections which are already loaded.  See the API docs for :meth:`~sqlalchemy.orm.query.Query.delete` for more details.
+
 Flushing
 --------