Function with_loader_criteria

lib/sqlalchemy/orm/_orm_constructors.py:860–1056

Add additional WHERE criteria to the load for all occurrences of a particular entity. .. versionadded:: 1.4 The :func:`_orm.with_loader_criteria` option is intended to add limiting criteria to a particular kind of entity in a query, **globally**, meaning it will apply to the en

(
    entity_or_base: _EntityType[Any],
    where_criteria: Union[
        _ColumnExpressionArgument[bool],
        Callable[[Any], _ColumnExpressionArgument[bool]],
    ],
    loader_only: bool = False,
    include_aliases: bool = False,
    propagate_to_loaders: bool = True,
    track_closure_variables: bool = True,
)

def with_loader_criteria(
    entity_or_base: _EntityType[Any],
    where_criteria: Union[
        _ColumnExpressionArgument[bool],
        Callable[[Any], _ColumnExpressionArgument[bool]],
    ],
    loader_only: bool = False,
    include_aliases: bool = False,
    propagate_to_loaders: bool = True,
    track_closure_variables: bool = True,
) -> LoaderCriteriaOption:
    """Add additional WHERE criteria to the load for all occurrences of
    a particular entity.

    .. versionadded:: 1.4

    The :func:`_orm.with_loader_criteria` option is intended to add
    limiting criteria to a particular kind of entity in a query,
    **globally**, meaning it will apply to the entity as it appears
    in the SELECT query as well as within any subqueries, join
    conditions, and relationship loads, including both eager and lazy
    loaders, without the need for it to be specified in any particular
    part of the query.    The rendering logic uses the same system used by
    single table inheritance to ensure a certain discriminator is applied
    to a table.

    E.g., using :term:`2.0-style` queries, we can limit the way the
    ``User.addresses`` collection is loaded, regardless of the kind
    of loading used::

        from sqlalchemy.orm import with_loader_criteria

        stmt = select(User).options(
            selectinload(User.addresses),
            with_loader_criteria(Address, Address.email_address != "foo"),
        )

    Above, the "selectinload" for ``User.addresses`` will apply the
    given filtering criteria to the WHERE clause.

    Another example, where the filtering will be applied to the
    ON clause of the join, in this example using :term:`1.x style`
    queries::

        q = (
            session.query(User)
            .outerjoin(User.addresses)
            .options(with_loader_criteria(Address, Address.email_address != "foo"))
        )

    The primary purpose of :func:`_orm.with_loader_criteria` is to use
    it in the :meth:`_orm.SessionEvents.do_orm_execute` event handler
    to ensure that all occurrences of a particular entity are filtered
    in a certain way, such as filtering for access control roles.    It
    also can be used to apply criteria to relationship loads.  In the
    example below, we can apply a certain set of rules to all queries
    emitted by a particular :class:`_orm.Session`::