Interface yii\db\ActiveQueryInterface

All Classes | Methods
Extendsyii\db\QueryInterface
Implemented byyii\db\ActiveQuery, yii\elasticsearch\ActiveQuery, yii\mongodb\ActiveQuery, yii\mongodb\file\ActiveQuery, yii\redis\ActiveQuery, yii\sphinx\ActiveQuery
Available since version2.0
Source Code https://github.com/yiisoft/yii2/blob/master/framework/db/ActiveQueryInterface.php

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 yii\db\ActiveQueryTrait and yii\db\ActiveRelationTrait.

Public Methods

Hide inherited methods

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

Method Details

Hide inherited methods

addOrderBy() public abstract method

Defined in: yii\db\QueryInterface::addOrderBy()

Adds additional ORDER BY columns to the query.

See also orderBy().

public abstract $this addOrderBy ( $columns )
$columns string|array

The columns (and the directions) to be ordered by. Columns can be specified in either a string (e.g. "id ASC, name DESC") or an array (e.g. ['id' => SORT_ASC, 'name' => SORT_DESC]). The method will automatically quote the column names unless a column contains some parenthesis (which means the column contains a DB expression).
return $this

The query object itself

 

                public function addOrderBy($columns);
all() public abstract method

Defined in: yii\db\QueryInterface::all()

Executes the query and returns all results as an array.

public abstract array all ( $db = null )
$db yii\db\Connection|null

The database connection used to execute the query. If this parameter is not given, the db application component will be used.
return array

The query results. If the query results in nothing, an empty array will be returned.

 

                public function all($db = null);
andFilterWhere() public abstract method

Defined in: yii\db\QueryInterface::andFilterWhere()

Adds an additional WHERE condition to the existing one ignoring empty parameters.

The new condition and the existing one will be joined using the 'AND' operator.

See also:

public abstract $this andFilterWhere ( array $condition )
$condition array

The new WHERE condition. Please refer to where() on how to specify this parameter.
return $this

The query object itself

 

                public function andFilterWhere(array $condition);
andWhere() public abstract method

Defined in: yii\db\QueryInterface::andWhere()

Adds an additional WHERE condition to the existing one.

The new condition and the existing one will be joined using the 'AND' operator.

See also:

public abstract $this andWhere ( $condition )
$condition array

The new WHERE condition. Please refer to where() on how to specify this parameter.
return $this

The query object itself

 

                public function andWhere($condition);
asArray() public abstract method

Sets the asArray() property.

public abstract $this asArray ( $value = true )
$value boolean

Whether to return the query results in terms of arrays instead of Active Records.
return $this

The query object itself

 

                public function asArray($value = true);
count() public abstract method

Defined in: yii\db\QueryInterface::count()

Returns the number of records.

public abstract integer|string|null count ( $q = '*', $db = null )
$q string

The COUNT expression. Defaults to '*'.
$db yii\db\Connection|null

The database connection used to execute the query. If this parameter is not given, the db application component will be used.
return integer|string|null

Number of records.

 

                public function count($q = '*', $db = null);
emulateExecution() public abstract method (available since version 2.0.11)

Defined in: yii\db\QueryInterface::emulateExecution()

Sets whether to emulate query execution, preventing any interaction with data storage.

After this mode is enabled, methods, returning query results like one(), all(), exists() and so on, will return empty or false values. You should use this method in case your program logic indicates query should not return any results, like in case you set false where condition like 0=1.

public abstract $this emulateExecution ( $value = true )
$value boolean

Whether to prevent query execution.
return $this

The query object itself.

 

                public function emulateExecution($value = true);
exists() public abstract method

Defined in: yii\db\QueryInterface::exists()

Returns a value indicating whether the query result contains any row of data.

public abstract boolean exists ( $db = null )
$db yii\db\Connection|null

The database connection used to execute the query. If this parameter is not given, the db application component will be used.
return boolean

Whether the query result contains any row of data.

 

                public function exists($db = null);
filterWhere() public abstract method

Defined in: yii\db\QueryInterface::filterWhere()

Sets the WHERE part of the query ignoring empty parameters.

See also:

public abstract $this filterWhere ( array $condition )
$condition array

The conditions that should be put in the WHERE part. Please refer to where() on how to specify this parameter.
return $this

The query object itself

 

                public function filterWhere(array $condition);
findFor() public abstract method

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.

public abstract mixed findFor ( $name, $model )
$name string

The relation name
$model yii\db\ActiveRecordInterface

The primary model
return mixed

The related record(s)

 

                public function findFor($name, $model);
indexBy() public abstract method

Sets the indexBy() property.

public abstract $this indexBy ( $column )
$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
}
return $this

The query object itself

 

                public function indexBy($column);
limit() public abstract method

Defined in: yii\db\QueryInterface::limit()

Sets the LIMIT part of the query.

public abstract $this limit ( $limit )
$limit integer|null

The limit. Use null or negative value to disable limit.
return $this

The query object itself

 

                public function limit($limit);
offset() public abstract method

Defined in: yii\db\QueryInterface::offset()

Sets the OFFSET part of the query.

public abstract $this offset ( $offset )
$offset integer|null

The offset. Use null or negative value to disable offset.
return $this

The query object itself

 

                public function offset($offset);
one() public abstract method

Executes query and returns a single row of result.

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

The DB connection used to create the DB command. If null, the DB connection returned by modelClass will be used.
return yii\db\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.

 

                public function one($db = null);
orFilterWhere() public abstract method

Defined in: yii\db\QueryInterface::orFilterWhere()

Adds an additional WHERE condition to the existing one ignoring empty parameters.

The new condition and the existing one will be joined using the 'OR' operator.

See also:

public abstract $this orFilterWhere ( array $condition )
$condition array

The new WHERE condition. Please refer to where() on how to specify this parameter.
return $this

The query object itself

 

                public function orFilterWhere(array $condition);
orWhere() public abstract method

Defined in: yii\db\QueryInterface::orWhere()

Adds an additional WHERE condition to the existing one.

The new condition and the existing one will be joined using the 'OR' operator.

See also:

public abstract $this orWhere ( $condition )
$condition array

The new WHERE condition. Please refer to where() on how to specify this parameter.
return $this

The query object itself

 

                public function orWhere($condition);
orderBy() public abstract method

Defined in: yii\db\QueryInterface::orderBy()

Sets the ORDER BY part of the query.

See also addOrderBy().

public abstract $this orderBy ( $columns )
$columns string|array

The columns (and the directions) to be ordered by. Columns can be specified in either a string (e.g. "id ASC, name DESC") or an array (e.g. ['id' => SORT_ASC, 'name' => SORT_DESC]). The method will automatically quote the column names unless a column contains some parenthesis (which means the column contains a DB expression).
return $this

The query object itself

 

                public function orderBy($columns);
via() public abstract method

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

public abstract $this via ( $relationName, callable $callable = null )
$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.
return $this

The relation object itself.

 

                public function via($relationName, callable $callable = null);
where() public abstract method

Defined in: yii\db\QueryInterface::where()

Sets the WHERE part of the query.

The $condition specified as an array can be in one of the following two formats:

  • hash format: ['column1' => value1, 'column2' => value2, ...]
  • operator format: [operator, operand1, operand2, ...]

A condition in hash format represents the following SQL expression in general: column1=value1 AND column2=value2 AND .... In case when a value is an array, an IN expression will be generated. And if a value is null, IS NULL will be used in the generated expression. Below are some examples:

  • ['type' => 1, 'status' => 2] generates (type = 1) AND (status = 2).
  • ['id' => [1, 2, 3], 'status' => 2] generates (id IN (1, 2, 3)) AND (status = 2).
  • ['status' => null] generates status IS NULL.

A condition in operator format generates the SQL expression according to the specified operator, which can be one of the following:

  • and: the operands should be concatenated together using AND. For example, ['and', 'id=1', 'id=2'] will generate id=1 AND id=2. If an operand is an array, it will be converted into a string using the rules described here. For example, ['and', 'type=1', ['or', 'id=1', 'id=2']] will generate type=1 AND (id=1 OR id=2). The method will not do any quoting or escaping.

  • or: similar to the and operator except that the operands are concatenated using OR. For example, ['or', ['type' => [7, 8, 9]], ['id' => [1, 2, 3]]] will generate (type IN (7, 8, 9) OR (id IN (1, 2, 3))).

  • not: this will take only one operand and build the negation of it by prefixing the query string with NOT. For example ['not', ['attribute' => null]] will result in the condition NOT (attribute IS NULL).

  • between: operand 1 should be the column name, and operand 2 and 3 should be the starting and ending values of the range that the column is in. For example, ['between', 'id', 1, 10] will generate id BETWEEN 1 AND 10.

  • not between: similar to between except the BETWEEN is replaced with NOT BETWEEN in the generated condition.

  • in: operand 1 should be a column or DB expression, and operand 2 be an array representing the range of the values that the column or DB expression should be in. For example, ['in', 'id', [1, 2, 3]] will generate id IN (1, 2, 3). The method will properly quote the column name and escape values in the range.

    To create a composite IN condition you can use and array for the column name and value, where the values are indexed by the column name: ['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ].

    You may also specify a sub-query that is used to get the values for the IN-condition: ['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]

  • not in: similar to the in operator except that IN is replaced with NOT IN in the generated condition.

  • like: operand 1 should be a column or DB expression, and operand 2 be a string or an array representing the values that the column or DB expression should be like. For example, ['like', 'name', 'tester'] will generate name LIKE '%tester%'. When the value range is given as an array, multiple LIKE predicates will be generated and concatenated using AND. For example, ['like', 'name', ['test', 'sample']] will generate name LIKE '%test%' AND name LIKE '%sample%'. The method will properly quote the column name and escape special characters in the values. Sometimes, you may want to add the percentage characters to the matching value by yourself, you may supply a third operand false to do so. For example, ['like', 'name', '%tester', false] will generate name LIKE '%tester'.

  • or like: similar to the like operator except that OR is used to concatenate the LIKE predicates when operand 2 is an array.

  • not like: similar to the like operator except that LIKE is replaced with NOT LIKE in the generated condition.

  • or not like: similar to the not like operator except that OR is used to concatenate the NOT LIKE predicates.

  • exists: operand 1 is a query object that used to build an EXISTS condition. For example ['exists', (new Query())->select('id')->from('users')->where(['active' => 1])] will result in the following SQL expression: EXISTS (SELECT "id" FROM "users" WHERE "active"=1).

  • not exists: similar to the exists operator except that EXISTS is replaced with NOT EXISTS in the generated condition.

  • Additionally you can specify arbitrary operators as follows: A condition of ['>=', 'id', 10] will result in the following SQL expression: id >= 10.

Note that this method will override any existing WHERE condition. You might want to use andWhere() or orWhere() instead.

See also:

public abstract $this where ( $condition )
$condition array

The conditions that should be put in the WHERE part.
return $this

The query object itself

 

                public function where($condition);
with() public abstract method

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();
public abstract $this with ( )
return $this

The query object itself

 

                public function with();