ActiveQueryInterface

API reference › yii › db › ActiveQueryInterface

interface	`yii\db\ActiveQueryInterface`
Extends	`QueryInterface`
Since	2.0
Source	`framework/db/ActiveQueryInterface.php`

Implemented by 1 type

ActiveQuery

ActiveQueryInterface defines the common interface to be implemented by active record query classes.

That are methods for either normal queries that return active records but also relational queries in which the query represents a relation between two active record classes and will return related records only.

A class implementing this interface should also use ActiveQueryTrait and ActiveRelationTrait.

Methods

Method	Description	Defined by
`addOrderBy()` abstract	Adds additional ORDER BY columns to the query.	`QueryInterface`
`all()` abstract	Executes the query and returns all results as an array.	`QueryInterface`
`andFilterWhere()` abstract	Adds an additional WHERE condition to the existing one ignoring empty parameters.	`QueryInterface`
`andWhere()` abstract	Adds an additional WHERE condition to the existing one.	`QueryInterface`
`asArray()` abstract	Sets the `asArray()` property.	`ActiveQueryInterface`
`count()` abstract	Returns the number of records.	`QueryInterface`
`emulateExecution()` abstract	Sets whether to emulate query execution, preventing any interaction with data storage.	`QueryInterface`
`exists()` abstract	Returns a value indicating whether the query result contains any row of data.	`QueryInterface`
`filterWhere()` abstract	Sets the WHERE part of the query ignoring empty parameters.	`QueryInterface`
`findFor()` abstract	Finds the related records for the specified primary record.	`ActiveQueryInterface`
`indexBy()` abstract	Sets the `indexBy()` property.	`ActiveQueryInterface`
`limit()` abstract	Sets the LIMIT part of the query.	`QueryInterface`
`offset()` abstract	Sets the OFFSET part of the query.	`QueryInterface`
`one()` abstract	Executes query and returns a single row of result.	`ActiveQueryInterface`
`orderBy()` abstract	Sets the ORDER BY part of the query.	`QueryInterface`
`orFilterWhere()` abstract	Adds an additional WHERE condition to the existing one ignoring empty parameters.	`QueryInterface`
`orWhere()` abstract	Adds an additional WHERE condition to the existing one.	`QueryInterface`
`via()` abstract	Specifies the relation associated with the junction table for use in relational query.	`ActiveQueryInterface`
`where()` abstract	Sets the WHERE part of the query.	`QueryInterface`
`with()` abstract	Specifies the relations with which this query should be performed.	`ActiveQueryInterface`

Method details

asArray()

abstract public function asArray(bool $value = true): $this

Sets the asArray() property.

Parameters

Parameter	Type	Description
`$value`	`bool`	Whether to return the query results in terms of arrays instead of Active Records.

Returns

$this: The query object itself

findFor()

abstract public function findFor(string $name, yii\db\ActiveRecordInterface $model): mixed

Finds the related records for the specified primary record.

This method is invoked when a relation of an ActiveRecord is being accessed in a lazy fashion.

Parameters

Parameter	Type	Description
`$name`	`string`	The relation name
`$model`	`ActiveRecordInterface`	The primary model

Returns

mixed: The related record(s)

indexBy()

abstract public function indexBy(string|callable $column): $this

Sets the indexBy() property.

Parameters

Parameter	Type	Description
`$column`	`string\|callable`	The name of the column by which the query results should be indexed by. This can also be a callable (e.g. anonymous function) that returns the index value based on the given row or model data. The signature of the callable should be: // $model is an AR instance when `asArray` is false, // or an array of column values when `asArray` is true. function ($model) { // return the index value corresponding to $model }

Returns

$this: The query object itself

one()

abstract public function one(yii\db\Connection|null $db = null): yii\db\ActiveRecordInterface|array|null

Executes query and returns a single row of result.

Parameters

Parameter	Type	Description
`$db`	`Connection\|null`	The DB connection used to create the DB command. If `null`, the DB connection returned by modelClass will be used.

Returns

ActiveRecordInterface|array|null: A single row of query result. Depending on the setting of asArray(), the query result may be either an array or an ActiveRecord object. null will be returned if the query results in nothing.

via()

abstract public function via(string $relationName, callable|null $callable = null): $this

Specifies the relation associated with the junction table for use in relational query.

Parameters

Parameter	Type	Description
`$relationName`	`string`	The relation name. This refers to a relation declared in the primaryModel of the relation.
`$callable`	`callable\|null`	A PHP callback for customizing the relation associated with the junction table. Its signature should be `function($query)`, where `$query` is the query to be customized.

Returns

$this: The relation object itself.

with()

abstract public function with(): $this

Specifies the relations with which this query should be performed.

The parameters to this method can be either one or multiple strings, or a single array of relation names and the optional callbacks to customize the relations.

A relation name can refer to a relation defined in modelClass or a sub-relation that stands for a relation of a related record. For example, orders.address means the address relation defined in the model class corresponding to the orders relation.

The following are some usage examples:

// find customers together with their orders and country
Customer::find()->with('orders', 'country')->all();
// find customers together with their orders and the orders' shipping address
Customer::find()->with('orders.address')->all();
// find customers together with their country and orders of status 1
Customer::find()->with([
    'orders' => function (\yii\db\ActiveQuery $query) {
        $query->andWhere('status = 1');
    },
    'country',
])->all();

Returns

$this: The query object itself