Skip to content

Improve docs related to memory usage and results buffering #8119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 23, 2025
+25 −45
Merged

Improve docs related to memory usage and results buffering #8119

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 13 additions & 22 deletions en/appendices/5-0-migration-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------
Expand Down
35 changes: 12 additions & 23 deletions en/orm/retrieving-data-and-resultsets.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
------------------------------------------------
Expand Down