From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 23 Jul 2012 14:28:52 +0000 (-0400)
Subject: add context to column_property docs illustrating the use of correlate_except()
X-Git-Tag: rel_0_8_0b1~306
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=ee0f80b4f028e27f35ae851e37e4070a9179b2a1;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add context to column_property docs illustrating the use of correlate_except()
to keep the non-correlated table from being correlated.  part of
[ticket:2530] but also mentioned in [ticket:2245] for some reason.
---

diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index 31e1d1fcdb..55c5af9794 100644
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -458,9 +458,30 @@ objects available for a particular ``User``::
         id = Column(Integer, primary_key=True)
         address_count = column_property(
             select([func.count(Address.id)]).\
-                where(Address.user_id==id)
+                where(Address.user_id==id).\
+                correlate_except(Address)
         )
 
+In the above example, we define a :func:`.select` construct like the following::
+
+    select([func.count(Address.id)]).\
+        where(Address.user_id==id).\
+        correlate_except(Address)
+
+The meaning of the above statement is, select the count of ``Address.id`` rows
+where the ``Address.user_id`` column is equated to ``id``, which in the context
+of the ``User`` class is the :class:`.Column` named ``id`` (note that ``id`` is
+also the name of a Python built in function, which is not what we want to use
+here - if we were outside of the ``User`` class definition, we'd use ``User.id``).
+
+The :meth:`.select.correlate_except` directive indicates that each element in the
+FROM clause of this :func:`.select` may be omitted from the FROM list (that is, correlated
+to the enclosing SELECT statement against ``User``) except for the one corresponding
+to ``Address``.  This isn't strictly necessary, but prevents ``Address`` from
+being inadvertently omitted from the FROM list in the case of a long string
+of joins between ``User`` and ``Address`` tables where SELECT statements against
+``Address`` are nested.
+
 If import issues prevent the :func:`.column_property` from being defined
 inline with the class, it can be assigned to the class after both
 are configured.   In Declarative this has the effect of calling :meth:`.Mapper.add_property`