add note re: pickling for loader criteria

Change-Id: I75992af71ba08799a03995178a6e4612c9a7428a
References: #8108

diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py
index e682828650f42f4544228f9411aae2be70e09fd7..6ef0a647f23ef13dd886b8ea82cf1a943f9ef751 100644 (file)
--- a/lib/sqlalchemy/orm/_orm_constructors.py
+++ b/lib/sqlalchemy/orm/_orm_constructors.py
@@ -724,11 +724,19 @@ def with_loader_criteria(
      accepts a target class as an argument, when the given class is
      a base with many different mapped subclasses.
 
+     .. note:: when the SQL expression is a lambda, **pickling is not
+        supported**.  Set
+        :paramref:`_orm.with_loader_criteria.propagate_to_loaders`
+        to ``False`` to prevent the object from being applied to instances.
+
     :param include_aliases: if True, apply the rule to :func:`_orm.aliased`
      constructs as well.
 
     :param propagate_to_loaders: defaults to True, apply to relationship
-     loaders such as lazy loaders.
+     loaders such as lazy loaders.   This indicates that the
+     option object itself including SQL expression is carried along with
+     each loaded instance.  Set to ``False`` to prevent the object from
+     being assigned to individual instances.
 
 
      .. seealso::