add more cross-linking / notes for yield_per, partitions

Change-Id: I0f8db2532827c76a2751186638d22104230db843
references: #8198
(cherry picked from commit 59bafe0fbefe16269c72ac39e699e4127d49841f)

diff --git a/doc/build/orm/queryguide.rst b/doc/build/orm/queryguide.rst
index 012206ba7c5ba6fe0af4bf821c919ae6d060d7bc..f3d4198398a432e45a79833d1cb79499f6c26104 100644 (file)
--- a/doc/build/orm/queryguide.rst
+++ b/doc/build/orm/queryguide.rst
@@ -1017,7 +1017,24 @@ often useful to use with a result partitioning method such as
     (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),)
     ...
 
-The purpose of this method is when fetching very large result sets
+For expediency, the :meth:`_engine.Result.yield_per` method may also be used
+with an ORM-enabled result set, which will have the same effect at result
+fetching time as if the ``yield_per`` execution option were used. The
+:meth:`_engine.Result.partitions` method, if used, automatically uses the
+number sent to :meth:`_engine.Result.yield_per` as the number of rows in each
+partition::
+
+    >>> stmt = select(User)
+    {sql}>>> for partition in session.execute(stmt).yield_per(10).partitions():
+    ...     for row in partition:
+    ...         print(row)
+    SELECT user_account.id, user_account.name, user_account.fullname
+    FROM user_account
+    [...] (){stop}
+    (User(id=1, name='spongebob', fullname='Spongebob Squarepants'),)
+    ...
+
+The purpose of "yield per" is when fetching very large result sets
 (> 10K rows), to batch results in sub-collections and yield them
 out partially, so that the Python interpreter doesn't need to declare
 very large areas of memory which is both time consuming and leads

diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index cb6906f0368762745718758e1e41bad410d8bd8f..6ca8f8c9d9dbc6c7be32c1ad7cce7c5558e63075 100644 (file)
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -804,6 +804,12 @@ class Result(_WithKeys, ResultInternal):
         :param num: number of rows to fetch each time the buffer is refilled.
          If set to a value below 1, fetches all rows for the next buffer.
 
+        .. seealso::
+
+            :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
+
+            :meth:`_engine.Result.partitions`
+
         """
         self._yield_per = num
 
@@ -997,6 +1003,13 @@ class Result(_WithKeys, ResultInternal):
         results, if possible.   Not all drivers support this option and
         the option is silently ignored for those who do not.
 
+        When using the ORM, the :meth:`_engine.Result.partitions` method
+        is typically more effective from a memory perspective when it is
+        combined with use of the :meth:`_engine.Result.yield_per` method,
+        which instructs the ORM loading internals to only build a certain
+        amount of ORM objects from a result at a time before yielding
+        them out.
+
         .. versionadded:: 1.4
 
         :param size: indicate the maximum number of rows to be present
@@ -1007,6 +1020,13 @@ class Result(_WithKeys, ResultInternal):
 
         :return: iterator of lists
 
+        .. seealso::
+
+            :paramref:`.Connection.execution_options.stream_results`
+
+            :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
+
+
         """
 
         getter = self._manyrow_getter