sqlalchemy.orm.events.QueryEvents

Receive the :class:`_query.Query` object before it is composed into a core :class:`_expression.Select` object. .. 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`

Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.delete`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_delete` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, this event should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_delete", retval=True) def no_deleted(query, delete_context): for desc in query.column_descriptions: if desc['type'] is User: entity = desc['entity'] query = query.filter(entity.deleted == False) return query :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "delete context" object. :param delete_context: a "delete context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_delete.delete_context`. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_update`

Allow modifications to the :class:`_query.Query` object within :meth:`_query.Query.update`. .. deprecated:: 1.4 The :meth:`_orm.QueryEvents.before_compile_update` event is superseded by the much more capable :meth:`_orm.SessionEvents.do_orm_execute` hook. Like the :meth:`.QueryEvents.before_compile` event, if the event is to be used to alter the :class:`_query.Query` object, it should be configured with ``retval=True``, and the modified :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_update", retval=True) def no_deleted(query, update_context): for desc in query.column_descriptions: if desc['type'] is User: entity = desc['entity'] query = query.filter(entity.deleted == False) update_context.values['timestamp'] = datetime.utcnow() return query The ``.values`` dictionary of the "update context" object can also be modified in place as illustrated above. :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "update context" object. :param update_context: an "update context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_update.update_context`. The object has a ``.values`` attribute in an UPDATE context which is the dictionary of parameters passed to :meth:`_query.Query.update`. This dictionary can be modified to alter the VALUES clause of the resulting UPDATE statement. .. versionadded:: 1.2.17 .. seealso:: :meth:`.QueryEvents.before_compile` :meth:`.QueryEvents.before_compile_delete`