Interface yii\db\ActiveQueryInterface
Extends | yii\db\QueryInterface |
---|---|
Implemented by | yii\db\ActiveQuery |
Available since version | 2.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
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
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. |
return | $this |
The query object itself |
---|
public function addOrderBy($columns);
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 |
return | array |
The query results. If the query results in nothing, an empty array will be returned. |
---|
public function all($db = null);
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);
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);
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);
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 |
return | integer|string|null |
Number of records. |
---|
public function count($q = '*', $db = null);
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);
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 |
return | boolean |
Whether the query result contains any row of data. |
---|
public function exists($db = null);
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);
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);
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:
|
return | $this |
The query object itself |
---|
public function indexBy($column);
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);
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);
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 |
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. |
---|
public function one($db = null);
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);
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);
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. |
return | $this |
The query object itself |
---|
public function orderBy($columns);
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 |
return | $this |
The relation object itself. |
---|
public function via($relationName, callable $callable = null);
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]
generatesstatus 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 generateid=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 generatetype=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 usingOR
. 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 conditionNOT (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 generateid BETWEEN 1 AND 10
.not between: similar to
between
except theBETWEEN
is replaced withNOT 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 generateid 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 thatIN
is replaced withNOT 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 generatename LIKE '%tester%'
. When the value range is given as an array, multipleLIKE
predicates will be generated and concatenated usingAND
. For example,['like', 'name', ['test', 'sample']]
will generatename 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 operandfalse
to do so. For example,['like', 'name', '%tester', false]
will generatename LIKE '%tester'
.or like: similar to the
like
operator except thatOR
is used to concatenate theLIKE
predicates when operand 2 is an array.not like: similar to the
like
operator except thatLIKE
is replaced withNOT LIKE
in the generated condition.or not like: similar to the
not like
operator except thatOR
is used to concatenate theNOT 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 thatEXISTS
is replaced withNOT 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);
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();
Signup or Login in order to comment.