# ActiveQueryInterface

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

[API reference](/docs/api/index.md) › [yii](/docs/api/yii/index.md) › [db](/docs/api/yii/db/index.md) › ActiveQueryInterface

| interface | `yii\db\ActiveQueryInterface` |
| --- | --- |
| Extends | [`QueryInterface`](/docs/api/yii/db/queryinterface/index.md) |
| Since | 2.0 |
| Source | [`framework/db/ActiveQueryInterface.php`](https://github.com/yiisoft/yii2/blob/22.0/framework/db/ActiveQueryInterface.php#L24) |

Implemented by 1 type:

- [`ActiveQuery`](/docs/api/yii/db/activequery/index.md)

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`](/docs/api/yii/db/activequerytrait/index.md) and [`ActiveRelationTrait`](/docs/api/yii/db/activerelationtrait/index.md).

## Methods

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

## Method details

### asArray() <span id="method-asArray"></span>

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

Sets the [`asArray()`](/docs/api/yii/db/activequeryinterface/index.md#method-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() <span id="method-findFor"></span>

```php
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`](/docs/api/yii/db/activerecordinterface/index.md) | The primary model |

**Returns**

`mixed`: The related record(s)

### indexBy() <span id="method-indexBy"></span>

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

Sets the [`indexBy()`](/docs/api/yii/db/activequeryinterface/index.md#method-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() <span id="method-one"></span>

```php
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`](/docs/api/yii/db/connection/index.md)`\|null` | The DB connection used to create the DB command. If `null`, the DB connection returned by [modelClass](/docs/api/yii/db/activequerytrait/index.md#property-modelClass) will be used. |

**Returns**

[`ActiveRecordInterface`](/docs/api/yii/db/activerecordinterface/index.md)`|array|null`: A single row of query result. Depending on the setting of [`asArray()`](/docs/api/yii/db/activequeryinterface/index.md#method-asArray), the query result may be either an array or an ActiveRecord object. `null` will be returned if the query results in nothing.

### via() <span id="method-via"></span>

```php
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](/docs/api/yii/db/activerelationtrait/index.md#property-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() <span id="method-with"></span>

```php
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](/docs/api/yii/db/activequerytrait/index.md#property-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