Document iterator memory usage workarounds. (#8116)

Author: dereuromark

en/appendices/5-0-migration-guide.rst

@@ -227,6 +227,38 @@ ORM
   ``$this->getSchema()`` inside the ``initialize()`` method.
 - ``SaveOptionsBuilder`` has been removed. Use a normal array for options instead.
 
+Known Issues
+------------
+
+**Memory Usage with extract() on Large Result Sets**
+
+When using ``extract()`` on large query results, you may experience higher memory
+usage compared to CakePHP 4.x. The collection iterator may materialize the entire
+result set into memory instead of processing results lazily.
+
+If you encounter memory issues when extracting values from large result sets,
+use one of these workarounds:
+
+**Option 1: Disable hydration and iterate manually**::
+
+    $query = $articles->find()
+        ->select(['id'])
+        ->disableHydration();
+
+    foreach ($query as $row) {
+        $id = $row['id'];
+        // Process each value
+    }
+
+**Option 2: Build your list while iterating**::
+
+    $query = $articles->find()->select(['id', 'title'])->disableHydration();
+
+    $ids = [];
+    foreach ($query as $row) {
+        $ids[] = $row['id'];
+    }
+
 Routing
 -------
 

en/orm/retrieving-data-and-resultsets.rst

@@ -981,6 +981,37 @@ The :doc:`/core-libraries/collections` chapter has more detail on what can be
 done with result sets using the collections features. The :ref:`format-results`
 section show how you can add calculated fields, or replace the result set.
 
+.. warning::
+
+    When working with large datasets, ``extract()`` may materialize the entire
+    result set into memory. If you encounter memory issues with large queries,
+    consider these alternatives:
+
+    **Option 1: Use disableHydration() with manual extraction**::
+
+        $query = $articles->find()
+            ->select(['id'])
+            ->disableHydration();
+
+        foreach ($query as $row) {
+            $id = $row['id'];
+            // Process individual values
+        }
+
+    **Option 2: Select only the fields you need**::
+
+        $query = $articles->find()
+            ->select(['id', 'title'])
+            ->disableHydration();
+
+        $ids = [];
+        foreach ($query as $row) {
+            $ids[] = $row['id'];
+        }
+
+    These approaches avoid loading unnecessary data and provide better memory
+    efficiency for large result sets.
+
 Getting the First & Last Record From a ResultSet
 ------------------------------------------------