From fec2b6560c14bb28ee7fc9d21028844acf700b04 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 14 Oct 2021 18:24:26 -0400 Subject: [PATCH] clarify that with_loader_criteria does not affect contains_eager() The ORM contains_eager() option does not affect the rendering of a SQL query in any way except that it adds additional columns to the columns clause of the SELECT. Therefore the with_loader_criteria() function has no interaction with this loader option. Fixes: #7189 Change-Id: I2e5439746de92382615b652c0e0801b6e48210c8 --- lib/sqlalchemy/orm/util.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 63a2774b31..8e0fd44cda 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -1012,6 +1012,13 @@ class LoaderCriteriaOption(CriteriaOption): argument. The given class will expand to include all mapped subclass and need not itself be a mapped class. + .. note:: The :func:`_orm.with_loader_criteria` option only applies to + loader options that **render their own SQL**, which means it does + **not** apply to the :func:`_orm.contains_eager` option. To apply + additional criteria to the JOIN used in conjunction with + :func:`_orm.contains_eager`, specify additional criteria within + the :meth:`_sql.select.join` or :meth:`_orm.Query.join` method. + .. warning:: The use of a lambda inside of the call to :func:`_orm.with_loader_criteria` is only invoked **once per unique class**. Custom functions should not be invoked within this lambda. -- 2.47.3