Classe « QueryEvents »

Méthode sqlalchemy.orm.QueryEvents.before_compile

Signature de la méthode before_compile

def before_compile(self, query) 

Description

before_compile.__doc__

Receive the :class:`_query.Query`
object before it is composed into a
core :class:`_expression.Select` object.

.. container:: event_signatures

     Example argument forms::

        from sqlalchemy import event


        @event.listens_for(SomeQuery, 'before_compile')
        def receive_before_compile(query):
            "listen for the 'before_compile' event"

            # ... (event handling logic) ...


.. deprecated:: 1.4  The :meth:`_orm.QueryEvents.before_compile` event
   is superseded by the much more capable
   :meth:`_orm.SessionEvents.do_orm_execute` hook.   In version 1.4,
   the :meth:`_orm.QueryEvents.before_compile` event is **no longer
   used** for ORM-level attribute loads, such as loads of deferred
   or expired attributes as well as relationship loaders.   See the
   new examples in :ref:`examples_session_orm_events` which
   illustrate new ways of intercepting and modifying ORM queries
   for the most common purpose of adding arbitrary filter criteria.


This event is intended to allow changes to the query given::

    @event.listens_for(Query, "before_compile", retval=True)
    def no_deleted(query):
        for desc in query.column_descriptions:
            if desc['type'] is User:
                entity = desc['entity']
                query = query.filter(entity.deleted == False)
        return query

The event should normally be listened with the ``retval=True``
parameter set, so that the modified query may be returned.

The :meth:`.QueryEvents.before_compile` event by default
will disallow "baked" queries from caching a query, if the event
hook returns a new :class:`_query.Query` object.
This affects both direct
use of the baked query extension as well as its operation within
lazy loaders and eager loaders for relationships.  In order to
re-establish the query being cached, apply the event adding the
``bake_ok`` flag::

    @event.listens_for(
        Query, "before_compile", retval=True, bake_ok=True)
    def my_event(query):
        for desc in query.column_descriptions:
            if desc['type'] is User:
                entity = desc['entity']
                query = query.filter(entity.deleted == False)
        return query

When ``bake_ok`` is set to True, the event hook will only be invoked
once, and not called for subsequent invocations of a particular query
that is being cached.

.. versionadded:: 1.3.11  - added the "bake_ok" flag to the
   :meth:`.QueryEvents.before_compile` event and disallowed caching via
   the "baked" extension from occurring for event handlers that
   return  a new :class:`_query.Query` object if this flag is not set.

.. seealso::

    :meth:`.QueryEvents.before_compile_update`

    :meth:`.QueryEvents.before_compile_delete`

    :ref:`baked_with_before_compile`