Interface yii\db\QueryInterface

Implemented byyii\db\ActiveQuery, yii\db\ActiveQueryInterface, yii\db\Query
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/QueryInterface.php

QueryInterface 定义了数据库查询要实现的最小方法集.

该接口的默认实现由 yii\db\QueryTrait 提供.

它支持获取 one() 实例或 all(). 允许通过 limit()offset() 进行分页. 通过 orderBy() 支持排序, 并且可以使用 where() 将项目限制为匹配某些条件.

公共方法

隐藏继承的方法

方法描述定义在
addOrderBy() 将其它 ORDER BY 列添加到查询中. yii\db\QueryInterface
all() 执行查询并以数组形式返回所有结果. yii\db\QueryInterface
andFilterWhere() 将一个 WHERE 条件添加到现有条件中, 忽略空参数. yii\db\QueryInterface
andWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryInterface
count() 返回记录数. yii\db\QueryInterface
emulateExecution() 设置是否模拟查询执行, 以防止与数据存储的任何交互. yii\db\QueryInterface
exists() 返回一个值, 该值指示查询结果是否包含任何数据行. yii\db\QueryInterface
filterWhere() 设置查询的 WHERE 部分, 忽略空参数. yii\db\QueryInterface
indexBy() 设置 indexBy() 属性. yii\db\QueryInterface
limit() 设置查询的 LIMIT 部分. yii\db\QueryInterface
offset() 设置查询的 OFFSET 部分. yii\db\QueryInterface
one() 执行查询并返回单行结果. yii\db\QueryInterface
orFilterWhere() 将一个 WHERE 条件添加到现有条件中, 忽略空参数. yii\db\QueryInterface
orWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryInterface
orderBy() 设置查询的 ORDER BY 部分. yii\db\QueryInterface
where() 设置查询的 WHERE 部分. yii\db\QueryInterface

方法详情

addOrderBy() public abstract 方法

将其它 ORDER BY 列添加到查询中.

参见 orderBy().

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

要排序的列(和方向). 列可以用字符串(eg. "id ASC, name DESC")或数组(eg. ['id' => SORT_ASC, 'name' => SORT_DESC])指定. 除非该列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用该列的名称.

return $this

查询对象本身.

all() public abstract 方法

执行查询并以数组形式返回所有结果.

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

用于执行查询的数据库连接. 如果未提供此参数(或null), 将会使用应用程序db组件.

return array

查询结果. 如果查询结果为空, 将返回一个空数组.

andFilterWhere() public abstract 方法

将一个 WHERE 条件添加到现有条件中, 忽略空参数.

新条件和现有条件将使用AND运算符合并.

参见:

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

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

andWhere() public abstract 方法

将一个 WHERE 条件添加到现有条件中.

新条件和现有条件将使用AND运算符合并.

参见:

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

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

count() public abstract 方法

返回记录数.

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

COUNT 表达式. 默认为*.

$db yii\db\Connection

用于执行查询的数据库连接. 如果未提供此参数(或null), 将会使用应用程序db组件.

return integer

记录数.

emulateExecution() public abstract 方法 (可用自版本: 2.0.11)

设置是否模拟查询执行, 以防止与数据存储的任何交互.

启用此模式后, 类似 one(), all(), exists() 等查询方法的结果, 将返回空值或false值. 如果你的程序逻辑指示查询不应返回任何结果, 则应使用此方法, 例如在条件0=1的情况下设置为false.

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

是否阻止查询执行.

return $this

查询对象本身..

exists() public abstract 方法

返回一个值, 该值指示查询结果是否包含任何数据行.

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

用于执行查询的数据库连接. 如果未提供此参数(或null), 将会使用应用程序db组件.

return boolean

查询结果是否包含任何数据行.

filterWhere() public abstract 方法

设置查询的 WHERE 部分, 忽略空参数.

参见:

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

应该放在 WHERE 部分的条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

indexBy() public abstract 方法

设置 indexBy() 属性.

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

查询结果所依据的列的名称. 这也可以是可调用的(eg. 匿名函数), 该调用基于给定的行数据返回索引值. 可调用对象的签名应该是:

function ($row)
{
    // 返回对应于 $row 的索引值
}
return $this

查询对象本身.

limit() public abstract 方法

设置查询的 LIMIT 部分.

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

限制. 使用null或负值来禁用限制.

return $this

查询对象本身.

offset() public abstract 方法

设置查询的 OFFSET 部分.

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

偏移量. 使用null或负值来禁用偏移.

return $this

查询对象本身.

one() public abstract 方法

执行查询并返回单行结果.

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

用于执行查询的数据库连接. 如果未提供此参数(或null), 将会使用应用程序db组件.

return array|boolean

查询结果的第一行(以数组表示). 如果查询结果为空, 则返回false.

orFilterWhere() public abstract 方法

将一个 WHERE 条件添加到现有条件中, 忽略空参数.

新条件和现有条件将使用OR运算符合并.

参见:

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

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

orWhere() public abstract 方法

将一个 WHERE 条件添加到现有条件中.

新条件和现有条件将使用OR运算符合并.

参见:

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

新的 WHERE 条件. 有关如何指定此参数, 请参考 where().

return $this

查询对象本身.

orderBy() public abstract 方法

设置查询的 ORDER BY 部分.

参见 addOrderBy().

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

要排序的列(和方向). 列可以用字符串(eg. "id ASC, name DESC")或数组(eg. ['id' => SORT_ASC, 'name' => SORT_DESC])指定. 除非该列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用该列的名称.

return $this

查询对象本身.

where() public abstract 方法

设置查询的 WHERE 部分.

指定为数组的$condition可以采用以下两种格式之一:

  • 散列格式: ['column1' => value1, 'column2' => value2, ...]
  • 运算符格式: [operator, operand1, operand2, ...]

散列格式的条件通常表示以下 SQL 表达式: column1=value1 AND column2=value2 AND .... 如果值是一个数组, 则将生成一个IN表达式. 如果值为null, 则将在生成的表达式中使用IS NULL. 以下是一些例子:

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

运算符格式的条件根据指定的运算符生成 SQL 表达式,该运算符可以是以下之一:

  • and: 操作数应使用AND连接在一起. 例如, ['and', 'id=1', 'id=2'] 将生成 id=1 AND id=2. 如果运算符是一个数组, 则将使用此处描述的规则将其转换字符串. 例如, ['and', 'type=1', ['or', 'id=1', 'id=2']] 将生成 type=1 AND (id=1 OR id=2). 该方法将进行任何引用或转义.

  • or: 类似于and运算符, 不同之处在于操作数使用OR来连接. 例如, ['or', ['type' => [7, 8, 9]], ['id' => [1, 2, 3]]] 将生成 (type IN (7, 8, 9) OR (id IN (1, 2, 3))).

  • not: 这将只使用一个操作数, 并通过在查询字符串前加上NOT来建立它的取反. 例如, ['not', ['attribute' => null]] 将生成条件 NOT (attribute IS NULL).

  • between: 操作数1应该是列名, 操作数2和3应该是列所在范围的起始值和结束值. 例如, ['between', 'id', 1, 10] 将生成 id BETWEEN 1 AND 10.

  • not between: 类似于between, 只是在生成的条件下, 将BETWEEN被替换为NOT BETWEEN.

  • in: 操作数1应该是列或DB表达式, 操作数2是表示列或DB表达式应该在的值的范围的数组. 例如, ['in', 'id', [1, 2, 3]] 将生成 id IN (1, 2, 3). 该方法将正确引用该范围内的列名和转义值. 要创建一个复合的IN条件, 你可以对列名和值使用数组, 其中值由列名索引: ['in', ['id', 'name'], [['id' => 1, 'name' => 'foo'], ['id' => 2, 'name' => 'bar']] ]. 你也可以指定一个子查询, 用于获取IN条件的值: ['in', 'user_id', (new Query())->select('id')->from('users')->where(['active' => 1])]

  • not in: 类似于in运算符, 只是在生成的条件下, 将IN被替换为NOT IN.

  • like: 操作数1应该是列或 DB 表达式, 而操作数2是表示列或DB表达式应该类似的值的字符串或数组. 例如: ['like', 'name', 'tester'] 将生成 name LIKE '%tester%'. 当值范围以数组形式给出时, 将生成多个LIKE谓词将并使用AND将其连接起来. 例如: ['like', 'name', ['test', 'sample']] 将生成 name LIKE '%test%' AND name LIKE '%sample%'. 该方法将正确引用列名称, 并在值中转义特殊字符. 有时, 你可能希望自己将百分比字符到匹配的值中, 你可以提供第三个操作数false来执行此操作. 例如: ['like', 'name', '%tester', false] 将生成 name LIKE '%tester'.

  • or like: 类似于like运算符, 不同之处在于, 当操作数2为数组时, 使用OR连接LIKE谓词.

  • not like: 类似于like运算符, 只是在生成的条件下, 将LIKE被替换为NOT LIKE.

  • or not like: 类似于not like运算符, 只是在生成的条件下, 使用OR连接NOT LIKE谓词.

  • exists: 操作数1是一个查询对象, 用于构建EXISTS条件. 例如, ['exists', (new Query())->select('id')->from('users')->where(['active' => 1])] 将生成表达式: EXISTS (SELECT "id" FROM "users" WHERE "active"=1).

  • not exists: 类似于exists运算符, 只是在生成的条件下, 将EXISTS被替换为NOT EXISTS.

  • 另外, 你可以指定任意的运算符, 如下所示: ['>=', 'id', 10] 会生成 id >= 10.

Note: 该方法将覆盖任何现有的 WHERE 条件. 你可能想改用 andWhere()orWhere().

参见:

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

应该放在 WHERE 部分的条件.

return $this

查询对象本身.