Sync documentation updates from cakephp-docs-md

  🤖 Generated with GitHub Actions from 2025-10-22 02:37:10 UTC

  Co-Authored-By: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: github-actions[bot]

docs/5.x/appendices/5-0-migration-guide.md

@@ -210,6 +210,41 @@ changes made:
   `$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**:
+
+``` php
+$query = $articles->find()
+    ->select(['id'])
+    ->disableHydration();
+
+foreach ($query as $row) {
+    $id = $row['id'];
+    // Process each value
+}
+```
+
+**Option 2: Build your list while iterating**:
+
+``` php
+$query = $articles->find()->select(['id', 'title'])->disableHydration();
+
+$ids = [];
+foreach ($query as $row) {
+    $ids[] = $row['id'];
+}
+```
+
 ### Routing
 
 - Static methods `connect()`, `prefix()`, `scope()` and `plugin()` of the `Router` have been removed and

docs/5.x/orm/retrieving-data-and-resultsets.md

@@ -1059,6 +1059,40 @@ The [Collections](../core-libraries/collections) chapter has more detail on what
 done with result sets using the collections features. The [Format Results](../orm/query-builder#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**:
+>
+> ``` php
+> $query = $articles->find()
+>     ->select(['id'])
+>     ->disableHydration();
+>
+> foreach ($query as $row) {
+>     $id = $row['id'];
+>     // Process individual values
+> }
+> ```
+>
+> **Option 2: Select only the fields you need**:
+>
+> ``` php
+> $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
 
 You can use the `first()` and `last()` methods to get the respective records