From ee0f80b4f028e27f35ae851e37e4070a9179b2a1 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 23 Jul 2012 10:28:52 -0400 Subject: [PATCH] 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. --- doc/build/orm/mapper_config.rst | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) 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` -- 2.47.3