# Interface yii\db\QueryInterface

Implemented by | yii\db\ActiveQuery, yii\db\ActiveQueryInterface, yii\db\Query, yii\elasticsearch\ActiveQuery, yii\elasticsearch\Query, yii\mongodb\ActiveQuery, yii\mongodb\Query, yii\mongodb\file\ActiveQuery, yii\mongodb\file\Query, yii\sphinx\ActiveQuery, yii\sphinx\Query
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/db/QueryInterface.php

The QueryInterface defines the minimum set of methods to be implemented by a database query.

The default implementation of this interface is provided by yii\db\QueryTrait.

It has support for getting one() instance or all(). Allows pagination via limit() and offset(). Sorting is supported via orderBy() and items can be limited to match some conditions using where().

## 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
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
indexBy() | Sets the indexBy() property. | yii\db\QueryInterface
limit() | Sets the LIMIT part of the query. | yii\db\QueryInterface
offset() | Sets the OFFSET part of the query. | yii\db\QueryInterface
one() | Executes the query and returns a single row of result. | yii\db\QueryInterface
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
where() | Sets the WHERE part of the query. | yii\db\QueryInterface

## Method Details

Hide inherited methods

addOrderBy() public abstract method

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

Source code

                    public function addOrderBy($columns);

all() public abstract method

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.

Source code

                    public function all($db = null);

andFilterWhere() public abstract method

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:

- filterWhere()
- orFilterWhere()

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

Source code

                    public function andFilterWhere(array $condition);

andWhere() public abstract method

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:

- where()
- orWhere()

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

Source code

                    public function andWhere($condition);

count() public abstract method

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.

Source code

                    public function count($q = '*', $db = null);

emulateExecution() public abstract method (available since version 2.0.11)

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.

Source code

                    public function emulateExecution($value = true);

exists() public abstract method

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.

Source code

                    public function exists($db = null);

filterWhere() public abstract method

Sets the WHERE part of the query ignoring empty parameters.

See also:

- andFilterWhere()
- orFilterWhere()

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

Source code

                    public function filterWhere(array $condition);

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 data. The signature of the callable should be:

    function ($row)
    {
        // return the index value corresponding to $row
    }

return | $this | The query object itself

Source code

                    public function indexBy($column);

limit() public abstract method

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

Source code

                    public function limit($limit);

offset() public abstract method

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

Source code

                    public function offset($offset);

one() public abstract method

Executes the query and returns a single row of result.

public abstract array|boolean one ( $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|boolean | The first row (in terms of an array) of the query result. False is returned if the query results in nothing.

Source code

                    public function one($db = null);

orFilterWhere() public abstract method

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:

- filterWhere()
- andFilterWhere()

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

Source code

                    public function orFilterWhere(array $condition);

orWhere() public abstract method

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:

- where()
- andWhere()

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

Source code

                    public function orWhere($condition);

orderBy() public abstract method

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

Source code

                    public function orderBy($columns);

where() public abstract method

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:

- andWhere()
- orWhere()

public abstract $this where ( $condition )
$condition | array | The conditions that should be put in the WHERE part.
return | $this | The query object itself

Source code

                    public function where($condition);