- The :class:`.Query` will raise an exception when :meth:`.Query.yield_per`

is used with mappings or options where eager loading, either
joined or subquery, would take place.  These loading strategies are
not currently compatible with yield_per, so by raising this error,
the method is safer to use - combine with sending False to
:meth:`.Query.enable_eagerloads` to disable the eager loaders.

2 files changed, 25 insertions, 0 deletions

diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst
index 13af7f953..016be974b 100644
--- a/doc/build/changelog/changelog_10.rst
+++ b/doc/build/changelog/changelog_10.rst
@@ -21,6 +21,19 @@
     series as well.  For changes that are specific to 1.0 with an emphasis
     on compatibility concerns, see :doc:`/changelog/migration_10`.
 
+    .. change::
+        :tags: feature, orm
+
+        The :class:`.Query` will raise an exception when :meth:`.Query.yield_per`
+        is used with mappings or options where eager loading, either
+        joined or subquery, would take place.  These loading strategies are
+        not currently compatible with yield_per, so by raising this error,
+        the method is safer to use - combine with sending False to
+        :meth:`.Query.enable_eagerloads` to disable the eager loaders.
+
+        .. seealso::
+
+            :ref:`migration_yield_per_eager_loading`
 
     .. change::
         :tags: bug, orm
diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst
index 8f78a94de..1aa0129c3 100644
--- a/doc/build/changelog/migration_10.rst
+++ b/doc/build/changelog/migration_10.rst
@@ -104,6 +104,18 @@ symbol, and no change to the object's state occurs.
 
 :ticket:`3061`
 
+.. _migration_yield_per_eager_loading:
+
+Joined/Subquery eager loading explicitly disallowed with yield_per
+------------------------------------------------------------------
+
+In order to make the :meth:`.Query.yield_per` method easier to use,
+an exception is raised if any joined or subquery eager loaders are
+to take effect when yield_per is used, as these are currently not compatible
+with yield-per (subquery loading could be in theory, however).
+When this error is raised, the :meth:`.Query.enable_eagerloads` method
+should be called with a value of False to disable these eager loaders.
+
 .. _migration_migration_deprecated_orm_events:
 
 Deprecated ORM Event Hooks Removed