diff --git a/en/appendices/5-0-migration-guide.rst b/en/appendices/5-0-migration-guide.rst index d81e7561de..d950fbed5d 100644 --- a/en/appendices/5-0-migration-guide.rst +++ b/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 ------- diff --git a/en/orm/retrieving-data-and-resultsets.rst b/en/orm/retrieving-data-and-resultsets.rst index 1ba55adf00..aa1293baa1 100644 --- a/en/orm/retrieving-data-and-resultsets.rst +++ b/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 ------------------------------------------------