BatchQueryResult

API reference › yii › db › BatchQueryResult

class	`yii\db\BatchQueryResult`
Extends	`yii\base\Component` » `yii\base\BaseObject`
Implements	`Iterator`, `yii\base\Configurable`
Since	2.0
Source	`framework/db/BatchQueryResult.php`

BatchQueryResult represents a batch query from which you can retrieve data in batches.

You usually do not instantiate BatchQueryResult directly. Instead, you obtain it by calling Query::batch() or Query::each(). Because BatchQueryResult implements the Iterator interface, you can iterate it to obtain a batch of data in each iteration. For example,

$query = (new Query)->from('user');
foreach ($query->batch() as $i => $users) {
    // $users represents the rows in the $i-th batch
}
foreach ($query->each() as $user) {
}

Properties

Property	Type	Description	Defined by
`$batchSize`	`int`	The number of rows to be returned in each batch. Default: `100`.	`BatchQueryResult`
`$behaviors` read-only	`array<yii\base\Behavior<static>>`	List of behaviors attached to this component.	`yii\base\Component`
`$db`	`Connection\|null`	The DB connection to be used when performing batch query. Default: `null`.	`BatchQueryResult`
`$each`	`bool`	Whether to return a single row during each iteration. Default: `false`.	`BatchQueryResult`
`$query`	`Query`	The query object associated with this batch query. Default: `null`.	`BatchQueryResult`

Methods

Method	Description	Defined by
`__construct()`	Constructor.	`yii\base\BaseObject`
`__call()`	Calls the named method which is not a class method.	`yii\base\Component`
`__clone()`	This method is called after the object is created by cloning an existing one.	`yii\base\Component`
`__destruct()`	Destructor.	`BatchQueryResult`
`__get()`	Returns the value of a component property.	`yii\base\Component`
`__isset()`	Checks if a property is set, i.e. defined and not null.	`yii\base\Component`
`__set()`	Sets the value of a component property.	`yii\base\Component`
`__unset()`	Sets a component property to be null.	`yii\base\Component`
`__wakeup()`	Unserialization is disabled to prevent remote code execution in case application calls unserialize() on user input containing specially crafted string.	`BatchQueryResult`
`attachBehavior()`	Attaches a behavior to this component.	`yii\base\Component`
`attachBehaviors()`	Attaches a list of behaviors to the component.	`yii\base\Component`
`behaviors()`	Returns a list of behaviors that this component should behave as.	`yii\base\Component`
`canGetProperty()`	Returns a value indicating whether a property can be read.	`yii\base\Component`
`canSetProperty()`	Returns a value indicating whether a property can be set.	`yii\base\Component`
`className()` static	Returns the fully qualified name of this class.	`yii\base\BaseObject`
`current()`	Returns the current dataset.	`BatchQueryResult`
`detachBehavior()`	Detaches a behavior from the component.	`yii\base\Component`
`detachBehaviors()`	Detaches all behaviors from the component.	`yii\base\Component`
`ensureBehaviors()`	Makes sure that the behaviors declared in `behaviors()` are attached to this component.	`yii\base\Component`
`getBehavior()`	Returns the named behavior object.	`yii\base\Component`
`getBehaviors()`	Returns all behaviors attached to this component.	`yii\base\Component`
`hasEventHandlers()`	Returns a value indicating whether there is any handler attached to the named event.	`yii\base\Component`
`hasMethod()`	Returns a value indicating whether a method is defined.	`yii\base\Component`
`hasProperty()`	Returns a value indicating whether a property is defined for this component.	`yii\base\Component`
`init()`	Initializes the object.	`yii\base\BaseObject`
`key()`	Returns the index of the current dataset.	`BatchQueryResult`
`next()`	Moves the internal pointer to the next dataset.	`BatchQueryResult`
`off()`	Detaches an existing event handler from this component.	`yii\base\Component`
`on()`	Attaches an event handler to an event.	`yii\base\Component`
`reset()`	Resets the batch query.	`BatchQueryResult`
`rewind()`	Resets the iterator to the initial state.	`BatchQueryResult`
`trigger()`	Triggers an event.	`yii\base\Component`
`valid()`	Returns whether there is a valid dataset at the current position.	`BatchQueryResult`
`fetchData()` protected	Fetches the next batch of data.	`BatchQueryResult`
`getRows()` protected	Reads and collects rows for batch	`BatchQueryResult`

Events

Event	Type	Description	Defined by
`EVENT_RESET`	`yii\db\Event`	An event that is triggered when the batch query is reset. Event name: `'reset'`. Available since 2.0.41.	`BatchQueryResult`
`EVENT_FINISH`	`yii\db\Event`	An event that is triggered when the last batch has been fetched. Event name: `'finish'`. Available since 2.0.41.	`BatchQueryResult`

Constants

Constant	Value	Description	Defined by
`MSSQL_NO_MORE_ROWS_ERROR_CODE`	`-13`	MSSQL error code for exception that is thrown when last batch is size less than specified batch size	`BatchQueryResult`

Property details

$db

public yii\db\Connection|null $db = null

The DB connection to be used when performing batch query.

If null, the “db” application component will be used.

$each

public bool $each = false

Whether to return a single row during each iteration.

If false, a whole batch of rows will be returned in each iteration.

$query

public yii\db\Query $query = null

The query object associated with this batch query.

Do not modify this property directly unless after reset() is called explicitly.

Method details

__destruct()

public function __destruct(): mixed

Destructor.

Returns

mixed

__wakeup()

public function __wakeup(): mixed

Unserialization is disabled to prevent remote code execution in case application calls unserialize() on user input containing specially crafted string.

Returns

mixed

Since

2.0.38

See also

https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2020-15148

current()

public function current(): yii\db\TValue

Returns the current dataset.

This method is required by the interface Iterator.

Returns

yii\db\TValue: The current dataset.

key()

public function key(): yii\db\TKey|null

Returns the index of the current dataset.

This method is required by the interface Iterator.

Returns

yii\db\TKey|null: The index of the current row.

next()

public function next(): mixed

Moves the internal pointer to the next dataset.

This method is required by the interface Iterator.

Returns

mixed

reset()

public function reset(): mixed

Resets the batch query.

This method will clean up the existing batch query so that a new batch query can be performed.

Returns

mixed

rewind()

public function rewind(): mixed

Resets the iterator to the initial state.

This method is required by the interface Iterator.

Returns

mixed

valid()

public function valid(): bool

Returns whether there is a valid dataset at the current position.

This method is required by the interface Iterator.

Returns

bool: Whether there is a valid dataset at the current position.

fetchData()

protected function fetchData(): array

Fetches the next batch of data.

Returns

array: The data fetched

Throws

Exception

getRows()

protected function getRows(): array

Reads and collects rows for batch

Returns

array

Since

2.0.23