sqlalchemy.orm.events.QueryEvents

class documentation

class QueryEvents(event.Events):

Represent events within the construction of a _query.Query object.

The _orm.QueryEvents hooks are now superseded by the _orm.SessionEvents.do_orm_execute event hook.

Class Method	`_listen`	Undocumented
Method	`before_compile`	Receive the `_query.Query` object before it is composed into a core `_expression.Select` object.
Method	`before_compile_delete`	Allow modifications to the `_query.Query` object within `_query.Query.delete`.
Method	`before_compile_update`	Allow modifications to the `_query.Query` object within `_query.Query.update`.
Class Variable	`_target_class_doc`	Undocumented

Inherited from Events:

Class Method	`_accept_with`	Undocumented
Class Method	`_clear`	Undocumented
Class Method	`_remove`	Undocumented
Static Method	`_set_dispatch`	Undocumented

@classmethod
def _listen(cls, event_key, retval=False, bake_ok=False, **kw):

overrides sqlalchemy.event.base.Events._listen

Undocumented

def before_compile(self, query):

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

Deprecated since version 1.4: The _orm.QueryEvents.before_compile event is superseded by the much more capable _orm.SessionEvents.do_orm_execute hook. In version 1.4, the _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 .QueryEvents.before_compile event by default will disallow "baked" queries from caching a query, if the event hook returns a new _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.

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

See Also

.QueryEvents.before_compile

.QueryEvents.before_compile_update

Parameters
query	a `_query.Query` instance; this is also the `.query` attribute of the given "delete context" object.
delete_context	a "delete context" object which is the same kind of object as described in :paramref:`.QueryEvents.after_bulk_delete.delete_context`.

def before_compile_update(self, query, update_context):

Allow modifications to the _query.Query object within _query.Query.update.

Deprecated since version 1.4: The _orm.QueryEvents.before_compile_update event is superseded by the much more capable _orm.SessionEvents.do_orm_execute hook.

Like the .QueryEvents.before_compile event, if the event is to be used to alter the _query.Query object, it should be configured with retval=True, and the modified _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.

New in version 1.2.17.