From 884b933189d3c04481ceb08e923924fdc8e72492 Mon Sep 17 00:00:00 2001 From: ADmad Date: Wed, 22 Oct 2025 09:03:34 +0530 Subject: [PATCH] Improve docs related to memory usage and results buffering --- en/appendices/5-0-migration-guide.rst | 35 +++++++++-------------- en/orm/retrieving-data-and-resultsets.rst | 35 ++++++++--------------- 2 files changed, 25 insertions(+), 45 deletions(-) diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index d950fbed5d..3c446cc881 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/en/appendices/5-0-migration-guide.rst @@ -230,34 +230,25 @@ ORM Known Issues ------------ -**Memory Usage with extract() on Large Result Sets** +**Memory usage with 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. +Compared to CakePHP 4.x, when working with large data sets (especially when +calling collection methods like ``extract()`` on the result set), you may encounter +high memory usage due to the entire result set being buffered in memory. -If you encounter memory issues when extracting values from large result sets, -use one of these workarounds: +You can work around this issue by disabling results buffering for the query:: -**Option 1: Disable hydration and iterate manually**:: + $results = $articles->find() + ->disableBufferedResults() + ->all(); - $query = $articles->find() - ->select(['id']) - ->disableHydration(); +Depending on your use case, you may also consider using disabling hydration:: - foreach ($query as $row) { - $id = $row['id']; - // Process each value - } - -**Option 2: Build your list while iterating**:: + $results = $articles->find() + ->disableHydration() + ->all(); - $query = $articles->find()->select(['id', 'title'])->disableHydration(); - - $ids = []; - foreach ($query as $row) { - $ids[] = $row['id']; - } +The above will disable creation of entity objects and return rows as arrays instead. Routing ------- diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index aa1293baa1..d6172ffbcb 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/en/orm/retrieving-data-and-resultsets.rst @@ -983,34 +983,23 @@ 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: + When working with large data sets (especially when calling collection methods + like ``extract()`` on the result set), you may encounter high memory usage + due to the entire result set being buffered in memory. - **Option 1: Use disableHydration() with manual extraction**:: + You can work around this issue by disabling results buffering for the query:: - $query = $articles->find() - ->select(['id']) - ->disableHydration(); + $results = $articles->find() + ->disableBufferedResults() + ->all(); - foreach ($query as $row) { - $id = $row['id']; - // Process individual values - } - - **Option 2: Select only the fields you need**:: + Depending on your use case, you may also consider using disabling hydration:: - $query = $articles->find() - ->select(['id', 'title']) - ->disableHydration(); - - $ids = []; - foreach ($query as $row) { - $ids[] = $row['id']; - } + $results = $articles->find() + ->disableHydration() + ->all(); - These approaches avoid loading unnecessary data and provide better memory - efficiency for large result sets. + The above will disable creation of entity objects and return rows as arrays instead. Getting the First & Last Record From a ResultSet ------------------------------------------------